mb/system76/rpl: darp9: Add SSD RTD3 configs

Some drives block the CPU from reaching C10 on suspend without the RTD3
config.

Fixes suspend with the following drives:

- Kingston KC3000 (SKC3000D/4096G)
- Kingston HyperX (SHPM2280P2H/240G)
- Solidigm P44 Pro (SSDPFKKW010X7)

The following drives continue to work:

- Samsung 970 Evo (MZVLB250HAHQ)
- WD Black SN770 (WDS250G3X0E)
- WD Green SN350 (WDS240G2G0C-00AJM0)
- WD Blue SN570 (WDS100T3B0C)

Change-Id: I205d78377fa2b0db8d37542cdb94ba86ded1d66e
Signed-off-by: Tim Crawford <tcrawford@system76.com>
Tested-by: Levi Portenier <levi@system76.com>

.checkpatch.conf

@@ -8,6 +8,9 @@
 --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

.clang-format

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

.editorconfig

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

.gitignore

@@ -9,7 +9,6 @@ defconfig
 build/
 coreboot-builds/
 coreboot-builds*/
-generated/
 
 site-local
 

.gitmodules

@@ -13,6 +13,9 @@
 [submodule "arm-trusted-firmware"]
 	path = 3rdparty/arm-trusted-firmware
 	url = https://review.coreboot.org/arm-trusted-firmware.git
+[submodule "3rdparty/chromeec"]
+	path = 3rdparty/chromeec
+	url = https://review.coreboot.org/chrome-ec.git
 [submodule "libhwbase"]
 	path = 3rdparty/libhwbase
 	url = https://review.coreboot.org/libhwbase.git
@@ -60,8 +63,5 @@
 	branch = stmpe
 [submodule "util/goswid"]
 	path = util/goswid
-	url = https://review.coreboot.org/goswid
+	url = https://review.coreboot.org/goswid.git
 	branch = trunk
-[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

.gitreview

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

AUTHORS

@@ -10,222 +10,73 @@
 
 3mdeb Embedded Systems Consulting
 9elements Agency GmbH
-Aamir Bohra
-Aaron Durbin
-Abe Levkoy
-Abel Briggs
 Abhinav Hardikar
-AdaCore
-Adam Liu
-Adam Mills
 Advanced Computing Lab, LANL
 Advanced Micro Devices, Inc.
+AdaCore
 AG Electronics Ltd.
-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
-Alper Nebi Yasak
-Amanda Hwang
-American Megatrends International, LLC
-Amersel
-Amit Caleechurn
 Analog Devices Inc.
 Analogix Semiconductor
-Anand Mistry
-Anand Vaikar
 Andre Heider
-Andrew McRae
-Andrew SH Cheng
-Andrey Pronin
 Andriy Gapon
 Andy Fleming
-Andy Pont
-Andy-ld Lu
 Angel Pons
-Anil Kumar K
-Anna Karaś
-Annie Chen
 Anton Kochkov
-Ao Zhong
-Appukuttan V K
-Arashk Mahshidfar
-Arec Kao
-Ariel Fang
 ARM Limited and Contributors
 Arthur Heymans
 Asami Doi
-Aseda Aboagye
-Ashish Kumar Mishra
-Ashqti
 ASPEED Technology Inc.
 Atheros Corporation
 Atmel Corporation
-Balaji Manigandan
-Balázs Vinarz
 BAP - Bruhnspace Advanced Projects
-Baruch Siach
-Ben Chuang
-Ben Kao
-Ben McMillen
-Ben Zhang
-Benjamin Doron
-Bernardo Perez Priego
-Bhanu Prakash Maiya
 Bill Xie
-Bin Meng
 Bitland Tech Inc.
-Bob Moragues
-Bora Guvendik
 Boris Barbulovski
-Boris Mittelberg
-Brandon Breitenstein
-Brandon Weeks
-Brian Norris
-Bryant Ou
 Carl-Daniel Hailfinger
-Casper Chang
-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
 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 Lin
-David Milosevic
 David Mosberger-Tang
 David Mueller
 David S. Peterson
-David Wu
-Dawei Chien
-Deepika Punyamurtula
-Deepti Deshatty
 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.
-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
-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
-Fabian Groffen
 Fabian Kunkel
-Fabian Meyer
-Fabio Aiuto
 Fabrice Bellard
 Facebook, Inc.
-Fei Yan
-Felix Friedlander
 Felix Held
 Felix Singer
-Fengquan Chen
-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
-Garmin Chang
 Gary Jennejohn
 George Trudeau
 Gerald Van Baren
@@ -233,581 +84,164 @@ Gerd Hoffmann
 Gergely Kiss
 Google LLC
 Greg Watson
-Grzegorz Bernacki
 Guennadi Liakhovetski
-Guodong Liu
-Gwendal Grignou
 Hal Martin
-Hao Chou
-Hao Wang
 HardenedLinux
-Harsha B R
-Harshit Sharma
-Henry C Chen
-Herbert Wu
-Hewlett Packard Enterprise Development LP
 Hewlett-Packard Development Company, L.P.
-Himanshu Sahdev
-Housong Zhang
-Hsiao Chien Sung
-Hsin-hsiung wang
-Hsin-Te Yuan
-Hsuan Ting Chen
-Huaqin Technology Co., Ltd
+Hewlett Packard Enterprise Development LP
 Huaqin Telecom Inc.
-Hui Liu
-Huijuan Xie
-Hung-Te Lin
-Ian Douglas Scott
-Ian Feng
 IBM Corporation
 Idwer Vollering
-Igor Bagnucki
 Igor Pavlov
-Ikjoon Jang
 Imagination Technologies
 Infineon Technologies
 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
-Jamie Chen
-Jamie Ryu
-Jan Dabros
-Jan Samek
-Jan Tatje
-Jason Glenesk
-Jason Nein
-Jason V Le
-Jason Z Chen
 Jason Zhao
-jason-ch chen
-Jason-jh Lin
-Jay Patel
-Jean Lucas
-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 Kitching
-Joel Linn
-Joey Peng
 Johanna Schander
-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 Tsai
-Julian Schroeder
-Julian Stecklina
-Julien Viard de Galbert
-Julius Werner
-Kacper Stojek
-Kaiyen Chang
-Kane Chen
-Kangheui Won
-Kapil Porwal
-Karol Zmyslowski
-Karthik Ramasubramanian
-Kei Hiroyoshi
 Keith Hui
 Keith Packard
-Kenneth Chan
-Kevin Chang
-Kevin Cheng
-Kevin Chiu
-Kevin Chowski
 Kevin Cody-Little
-Kevin Keijzer
 Kevin O'Connor
-Kevin3 Yang
-kewei xu
-Kilari Raasi
-Kirk Wang
-Konrad Adamczyk
 Kontron Europe GmbH
-Kornel Dulęba
-Krishna P Bhat D
-Krystian Hebel
 Kshitij
-Kshitiz Godara
-Kulkarni. Srinivas
-Kun Liu
-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
-Liya Li
 Lubomir Rintel
 Luc Verhaegen
-Lucas Chen
-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 Hasemeyer
-Mark Hsieh
-Mars Chen
-Marshall Dawson
 Martin Mares
 Martin Renters
 Martin Roth
 Marvell International Ltd.
 Marvell Semiconductor Inc.
-Marx Wang
-Masanori Ogino
-Máté Kukri
-Matei Dibu
-Mathew King
-Matt Chen
-Matt Delco
 Matt DeVillier
-Matt Papageorge
-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
-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ł Żygowski
-Micro-Star INT'L CO., LTD.
+Michael Niewöhner
 Mika Westerberg
-Mike Banon
-Mike Shih
-Miriam Polzer
-mkurumel
-Moises Garcia
 Mondrian Nuessle
-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 Vaccaro
 Nico Huber
 Nico Rikken
 Nicola Corna
-Nicolas Boichat
-Nicole Faerber
-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
-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
-Piotr Kleinschmidt
-Po Xu
-Poornima Tom
-Prasad Malisetty
-Prashant Malani
-Pratik Vishwakarma
-Pratikkumar Prajapati
-Pratikkumar V Prajapati
 Protectli
 Purism SPC
-Purism, SPC
-Qii Wang
-Qinghong Zeng
-Qualcomm Technologies, Inc.
-Quanta Computer INC
-Raihow Shi
-Rajat Jain
-Rajesh Patil
+Qualcomm Technologies
 Raptor Engineering, LLC
-Rasheed Hsueh
-Raul Rangel
-Ravi Kumar
-Ravi Mistry
-Ravindra
-Ravishankar Sarawadi
-Ray Han Lim Ng
-Raymond Chung
 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
-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 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
-Saurabh Mishra
 SciTech Software, Inc.
-Scott Chao
-SDC Systems Ltd
-Sean Rhodes
-Sebastian 'Swift Geek' Grzywna
+Sebastian Grzywna
 secunet Security Networks AG
-Selma Bensaid
-Semihalf
-Sen Chu
 Sencore Inc
 Sergej Ivanov
-Sergii Dmytruk
-Serin Yeh
-Seven Lee
-SH Kim
-Shahina Shaik
-Shaocheng Wang
-Shaoming Chen
-Shaunak Saha
-Shelley Chen
-Shelly Chang
-Sheng-Liang Pan
-Shiyu Sun
-Shon Wang
-Shou-Chieh Hsu
-Shreesh Chhabbi
-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
-Sridhar Siricilla
-Srinidhi N Kaushik
-Srinivasa Rao Mandadapu
-ST Microelectronics
-Stanley Wu
-Star Labs Online Ltd
-Stefan Binding
-Stefan Ott
 Stefan Reinauer
 Stefan Tauner
-Stephen Edworthy
 Steve Magnani
 Steve Shenton
-Subrata Banik
-Sudheer Amrabadi
-Sugnan Prabhu S
-Sukumar Ghorai
-Sumeet R Pawnikar
-Sunwei Li
+ST Microelectronics
 SUSE LINUX AG
 Sven Schnelle
 Syed Mohammed Khasim
-System76, Inc.
-szarpaj
-T Michael Turney
-TangYiwei
-Taniya Das
-Tao Xia
-Tarun Tuli
-Teddy Shih
-Terry Chen
+System76
 Texas Instruments
 The Android Open Source Project
 The ChromiumOS Authors
 The Linux Foundation
 The Regents of the University of California
-Thejaswani Putta
-Thomas Heijligen
 Thomas Winischhofer
-Tim Chen
-Tim Chu
-Tim Crawford
-Tim Van Patten
-Tim Wawrzynczak
-Timofey Komarov
 Timothy Pearson
-tinghan shen
 Tobias Diedrich
-Tom Hiller
-Tommie Lin
-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
-Václav Straka
-Vadim Bendebury
-Van Chen
-Varshit B Pandya
-Veerabhadrarao Badiganti
-Venkat Thogaru
-Venkata Krishna Nimmagadda
 VIA Technologies, Inc
-Victor Ding
-Vidya Gopalakrishnan
 Vikram Narayanan
-Vikrant L Jadeja
-Vinod Polimera
 Vipin Kumar
-Vitaly Rodionov
 Vladimir Serbinenko
 Vlado Cibic
-Vsujithk
 Wang Qing Pei
-Wanghao11
 Ward Vandewege
-Wayne Wang
-Weimin Wu
-Weiyi Lu
-Wenbin Mei
-Wentao Qin
-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
-Xixi Chen
-Xuxin Xiong
 YADRO
-Yan Liu
-Yang Wu
 Yann Collet
-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
-Yunlong Jia
-Yuval Peress
 Zachary Yedidia
-Zanxi Chen
-Zhanyong Wang
-Zheng Bao
-Zhenguo Li
-Zhi7 Li
-Zhiqiang Ma
-Zhixing Ma
-Zhiyong Tao
-Zhongtian Wu
-Zhuohao Lee
-Ziang Wang
-Zoey Wu
-Zoltan Baldaszti
-小田喜陽彦
-忧郁沙茶
-陳建宏

Documentation/Makefile

@@ -4,21 +4,47 @@
 # hacked together by Stefan Reinauer <stepan@openbios.org>
 #
 
-BUILDDIR ?= _build
-SPHINXOPTS ?= -j auto
+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 +52,5 @@ clean: clean-sphinx
 distclean: clean
 	rm -f corebootPortingGuide.pdf
 
-livesphinx: $(BUILDDIR)
-	$(MAKE) -f Makefile.sphinx livehtml BUILDDIR="$(BUILDDIR)"
-
-test:
-	@echo "Test for logging purposes - Failing tests will not fail the build"
-	-$(MAKE) -f Makefile.sphinx clean && $(MAKE) -k -f Makefile.sphinx html
-
-help:
-	@echo "all            - Builds all documentation targets"
-	@echo "sphinx         - Builds html documentation in _build directory"
-	@echo "clean          - Cleans intermediate files"
-	@echo "clean-sphinx   - Removes sphinx output files"
-	@echo "distclean      - Removes PDF files as well"
-	@echo "test           - Runs documentation tests"
-	@echo
-	@echo "  Makefile.sphinx builds - run with $(MAKE) -f Makefile-sphinx [target]"
-	@echo
-	@$(MAKE) -s -f Makefile.sphinx help 2>/dev/null
-
-.phony: help livesphinx sphinx test
-.phony: distclean clean clean-sphinx
+livesphinx:
+	$(MAKE) -f Makefile.sphinx livehtml SPHINXOPTS="$(SPHINXOPTS)"

Documentation/Makefile.sphinx

@@ -1,20 +1,60 @@
 ## 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:
@@ -23,7 +63,172 @@ livehtml:
 	@echo
 	$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sphinx
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

Documentation/acpi/index.md

@@ -5,34 +5,8 @@ backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
 upwards.
 
 
-```{toctree}
-:maxdepth: 1
-
-SSDT UID generation <uid.md>
-```
+- [SSDT UID generation](uid.md)
 
 ## GPIO
 
-```{toctree}
-:maxdepth: 1
-
-GPIO toggling in ACPI AML <gpio.md>
-```
-
-## Windows-specific ACPI documentation
-
-```{toctree}
-:maxdepth: 1
-
-Windows-specific documentation <windows.md>
-```
-
-##  ACPI specification - Useful links
-
-```{toctree}
-:maxdepth: 1
-
-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>
-```
+- [GPIO toggling in ACPI AML](gpio.md)

Documentation/acpi/windows.md

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

Documentation/acronyms.md

@@ -1,5 +1,7 @@
 # Firmware and Computer Acronyms, Initialisms and Definitions
 
+** Note that this document even more of a work in progress than most **
+** of the coreboot documentation **
 
 ## _0-9
 
@@ -18,25 +20,24 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   initialization that happens from the PSP.  Significantly, Memory
   Initialization.
 * AC - Electricity: [**Alternating Current**](https://en.wikipedia.org/wiki/Alternating_current)
-* Ack - Acknowledgment / Acknowledged
+* Ack - Acknowledgment
 * ACM – [**Authenticated Code Module**](https://doc.coreboot.org/security/intel/acm.html)
 * ACP - [**Average CPU power**](https://en.wikipedia.org/wiki/Thermal_design_power)
 * ACPI - The [**Advanced Configuration and Power
   Interface**](http://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface)
   is an industry standard for letting the OS control power management.
-  * [https://uefi.org/specifications](https://uefi.org/specifications)
+  * [http://www.acpi.info/](http://www.acpi.info/)
   * [http://kernelslacker.livejournal.com/88243.html](http://kernelslacker.livejournal.com/88243.html)
 * ADC - [**Analog-to-Digital Converter**](https://en.wikipedia.org/wiki/Analog-to-digital_converter)
 * ADL - Intel: [**Alder Lake**](https://en.wikichip.org/wiki/intel/microarchitectures/alder_lake)
 * AES - [**Advanced Encryption Standard**](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
-* AESKL - Intel: AES Key Locker
 * AGESA - [**AMD Generic Encapsulated Software Architecture**](https://en.wikipedia.org/wiki/AGESA_)
 * AGP - The [**Accelerated Graphics
-  Port**](https://en.wikipedia.org/wiki/Accelerated_Graphics_Port) is an
+  Port**](http://en.wikipedia.org/wiki/Accelerated_Graphics_Port) is an
   older (1997-2004) point-to-point bus for video cards to communicate
   with the processor.
 * AHCI - The [**Advanced Host Controller
-  Interface**](https://en.wikipedia.org/wiki/Advanced_Host_Controller_Interface)
+  Interface**](http://en.wikipedia.org/wiki/Advanced_Host_Controller_Interface)
   is a standard register set for communicating with a SATA controller.
   * [http://www.intel.com/technology/serialata/ahci.htm](http://www.intel.com/technology/serialata/ahci.htm)
   * [http://download.intel.com/technology/serialata/pdf/rev1_3.pdf](http://download.intel.com/technology/serialata/pdf/rev1_3.pdf)
@@ -50,11 +51,10 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   An open standard to connect and manage functional blocks in an SoC
   (System on a Chip)
 * AMD64 - Another name for [**x86-64**](https://en.wikipedia.org/wiki/X86-64)
-* AMD-Vi AMD: The AMD name for their IOMMU implementation
 * AMPL - AMD: [**Advanced Platform Management Link**](https://web.archive.org/web/20220509053546/https://developer.amd.com/wordpress/media/2012/10/419181.pdf) - Also referred to as
   SBI: Sideband Interface
 * AMT - Intel: [**Active Management Technology**](https://en.wikipedia.org/wiki/Intel_Active_Management_Technology)
-* ANSI - [**American National Standards Institute**](https://en.wikipedia.org/wiki/American_National_Standards_Institute)
+* ANSI - [**American National Standards Institute**](American_National_Standards_Institute)
 * AOAC - AMD: Always On, Always Connected
 * AP - Application processor - The main processor on the board (as
   opposed to the embedded controller or other processors that may be on
@@ -63,7 +63,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * APCB - AMD: AMD PSP Customization Block
 * API - [**Application Programming Interface**](https://en.wikipedia.org/wiki/API)
 * APIC - [**Advanced Programmable Interrupt
-  Controller**](https://en.wikipedia.org/wiki/Advanced_Programmable_Interrupt_Controller)
+  Controller**](http://en.wikipedia.org/wiki/Advanced_Programmable_Interrupt_Controller)
   this is an advanced version of a PIC that can handle interrupts from
   and for multiple CPUs. Modern systems usually have several APICs:
   Local APICs (LAPIC) are CPU-bound, IO-APICs are bridge-bound.
@@ -90,7 +90,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * ASPM - PCI: [**Active State Power
   Management**](https://en.wikipedia.org/wiki/Active_State_Power_Management)
 * ATA - [**Advanced Technology Attachment**](https://en.wikipedia.org/wiki/Parallel_ATA)
-* ATS - PCIe: Address Translation Services
 * ATAPI - [**ATA Packet Interface**](https://en.wikipedia.org/wiki/Parallel_ATA#ATAPI)
 * ATX - [**Advanced Technology eXtended**](https://en.wikipedia.org/wiki/ATX)
 * AVX -  [**Advanced Vector Extensions**](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions)
@@ -98,7 +97,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 
 ## B
 
-* BAR - [**Base Address Register**](https://en.wikipedia.org/wiki/Base_Address_Register) This generally refers to one of the
+* BAR - [**Base Address Register**](http://en.wikipedia.org/wiki/Base_Address_Register) This generally refers to one of the
   base address registers in the PCI config space of a PCI device
 * Baud - [**Baud**](https://en.wikipedia.org/wiki/Baud) - Not an acronym - Symbol rate unit of symbols per second, named
   after Émile Baudot
@@ -117,7 +116,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   the entire 4GiB of the 32-bit address space. Also known as flat mode
   or [**Unreal mode**](https://en.wikipedia.org/wiki/Unreal_mode).
 * BIOS - [**Basic Input/Output
-  System**](https://en.wikipedia.org/wiki/BIOS)
+  System**](http://en.wikipedia.org/wiki/BIOS)
 * BIST - The [**Built-in Self Test**](https://en.wikipedia.org/wiki/Built-in_self-test) is a test run by the processor on
   itself when it is first started. Usually, any nonzero value indicates
   that the selftest failed.
@@ -183,7 +182,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   generally used to describe a section of NVRAM (Non-volatile RAM), in
   this case a section battery-backed memory in the RTC (Real Time Clock)
   that is typically used to store BIOS settings.
-  *[https://en.wikipedia.org/wiki/Nonvolatile_BIOS_memory](https://en.wikipedia.org/wiki/Nonvolatile_BIOS_memory)
+  *[http://en.wikipedia.org/wiki/Nonvolatile_BIOS_memory](http://en.wikipedia.org/wiki/Nonvolatile_BIOS_memory)
 * CNL - Intel: [**Cannon Lake**](https://en.wikichip.org/wiki/intel/microarchitectures/cannon_lake) (formerly Skymont)
 * CNVi - Intel: [**Connectivity Integration**](https://en.wikipedia.org/wiki/CNVi)
 * CPL - x86: Current Privilege Level - Privilege levels range from 0-3; lower numbers are more privileged.
@@ -191,14 +190,14 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * CPPC - AMD: Collaborative Processor Performance Controls
 * CPS - Characters Per Second
 * CPU - [**Central Processing
-  Unit**](https://en.wikipedia.org/wiki/Central_processing_unit)
+  Unit**](http://en.wikipedia.org/wiki/Central_processing_unit)
 * CPUID - x86: [**CPU Identification**](https://en.wikipedia.org/wiki/CPUID) opcode
 * Cr50 - Google: The first generation Google Security Chip (GSC) used on
   ChromeOS devices.
 * CRB - Customer Reference Board
 * CRLF - Carriage Return, Line Feed - \\r\\n - The standard window EOL
   (End-of-Line) marker.
-* crt0 - [**C Run Time 0**](https://en.wikipedia.org/wiki/Crt0)
+* crt0 - [**C Run Time 0**](http://en.wikipedia.org/wiki/Crt0)
 * crt0s - crt0 Source code
 * CRT - [**Cathode Ray Tube**](https://en.wikipedia.org/wiki/Cathode-ray_tube)
 * CSE - Intel: Converged Security Engine
@@ -207,7 +206,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * CSME - Intel: Converged Security and Management Engine
 * CTLE - Intel: Continuous Time Linear Equalization
 * CVE - [**Common Vulnerabilities and Exposures**](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures)
-* CXMT - ChangXin Memory Technologies
 * CZN - AMD: [**Cezanne**](https://en.wikichip.org/wiki/amd/cores/cezanne) - CPU Family 19h, Model 50h
 
 
@@ -226,9 +224,8 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   still has power.
 * D3 Cold - ACPI Device power state: Power is completely removed from
   the device.
-* DASH - [**Desktop and mobile Architecture for System Hardware**](https://en.wikipedia.org/wiki/Desktop_and_mobile_Architecture_for_System_Hardware)
+* DASH - [**Desktop and mobile Architecture for System Hardware**](Desktop_and_mobile_Architecture_for_System_Hardware)
 * DB - DaughterBoard
-* DbC - USB: Debug Capability on the USB host controller
 * DC - Electricity: Direct Current
 * DCP - Digital Content Protection
 * DCR - **Decode Control Register** This is a way of identifying the
@@ -237,14 +234,13 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * DDI -  Intel: Digital Display Interface
 * DDR - [**Double Data Rate**](https://en.wikipedia.org/wiki/Double_data_rate)
 * DEVAPC - Mediatek: Device Access Permission Control
-* DF - Data Fabric
 * DFP - USB: Downstream Facing port
 * DHCP - [**Dynamic Host Configuration Protocol**](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
 * DID - Device Identifier
 * DIMM - [**Dual Inline Memory Module**](https://en.wikipedia.org/wiki/DIMM)
 * DIP - [**Dual inline package**](https://en.wikipedia.org/wiki/Dual_in-line_package)
 * DMA - [**Direct Memory
-  Access**](https://en.wikipedia.org/wiki/Direct_memory_access) Allows
+  Access**](http://en.wikipedia.org/wiki/Direct_memory_access) Allows
   certain hardware subsystems within a computer to access system memory
   for reading and/or writing independently of the main CPU. Examples of
   systems that use DMA: Hard Disk Controller, Disk Drive Controller,
@@ -252,7 +248,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   computers, as it allows devices of different speeds to communicate
   without subjecting the CPU to a massive interrupt load.
 * DMI - Direct Media Interface is a link/bus between CPU and PCH.
-* DMI - [**Desktop Management Interface**](https://en.wikipedia.org/wiki/Desktop_Management_Interface)
+* DMI - [**Desktop Management Interface**](Desktop_Management_Interface)
 * DMIC - Digital Microphone
 * DMTF - [**Distributed Management Task Force**](https://en.wikipedia.org/wiki/Distributed_Management_Task_Force)
 * DMZ - Demilitarized Zone
@@ -261,7 +257,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * DOS - Disk Operating System
 * DP - DisplayPort
 * DPM - Mediatek: DRAM Power Manager
-* DPTC - AMD: Dynamic Power and Thermal Control
 * DPTF - Intel: Dynamic Power and Thermal Framework
 * DRAM - Memory: [**Dynamic Random Access Memory**](https://en.wikipedia.org/wiki/Dynamic_random-access_memory)
 * DRTM - Dynamic Root of Trust for Measurement
@@ -287,8 +282,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * dTPM - Discrete TPM (Trusted Platform Module) - A separate TPM chip,
   vs Integrated TPMs or fTPMs (Firmware TPMs).
 * DTS - U-Boot: Device Tree Source
-* DUT - Device Under Test
-* DvC - USB: Debug Capability on the USB Device (Device Capability)
 * DVFS - ARM: Dynamic Voltage and Frequency Scaling
 * DVI - [**Digital Video Interface**](https://en.wikipedia.org/wiki/Digital_Visual_Interface)
 * DVT - Production Timeline: Design Validation Test
@@ -301,13 +294,11 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 
 ## E
 
-* EAPD - Intel: [**External Amplifier Power Down**](https://web.archive.org/web/20210203194800/https://www.eeweb.com/hd-audio-eapd/)
 * EBDA - Extended BIOS Data Area
-* EBG - Intel: Emmitsburg PCH
 * ECC - [**Error Correction Code**](https://en.wikipedia.org/wiki/Error_correction_code) - Typically used to refer to a type of
   memory that can detect and correct memory errors.
 * EDID - [**Extended Display Identification Data**](https://en.wikipedia.org/wiki/Extended_Display_Identification_Data)
-* EDK2 - EFI Development Kit 2
+* edk2 - EFI Development Kit 2
 * EDO - Memory: [**Extended Data
   Out**](https://en.wikipedia.org/wiki/Dynamic_random-access_memory#Extended_data_out_DRAM)
   - A DRAM standard introduced in 1994 that improved upon, but was
@@ -317,7 +308,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * EEPROM - [**Electrically Erasable Programmable ROM**](https://en.wikipedia.org/wiki/EEPROM) (common mistake:
   electrical erasable programmable ROM).
 * EFI - [**Extensible Firmware Interface**](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface)
-* EFS - AMD: Embedded Firmware Structure: The data structure that AMD processors look for first in the boot ROM to start the boot process.
 * EHCI - [**Enhanced Host Controller Interface**](https://en.wikipedia.org/wiki/Host_controller_interface_%28USB%2C_Firewire%29#EHCI) - USB 2.0
 * EHL - Intel: [**Elkhart Lake**](https://en.wikichip.org/wiki/intel/cores/elkhart_lake)
 * EIDE - Enhanced Integrated Drive Electronics
@@ -329,7 +319,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * EOL - End of Life
 * EPP - Intel: Energy-Performance Preference
 * EPROM - Erasable Programmable Read-Only Memory
-* EROFS - Linux: [**Enhanced Read-Only File System**](https://en.wikipedia.org/wiki/EROFS)
 * ESD - Electrostatic discharge
 * eSPI - Enhanced System Peripheral Interface
 * EVT - Production Timeline: Engineering Validation Test
@@ -340,7 +329,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * FADT - ACPI Table: Fixed ACPI Description Table
 * FAE - Field Application Engineer
 * FAT - File Allocation Table
-* FBVDDQ - Nvidia Power: Framebuffer Voltage
 * FCH - AMD: Firmware Control Hub
 * FCS - Production Timeline: First Customer Shipment
 * FDD - Floppy Disk Drive
@@ -358,7 +346,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * FPDT - ACPI: Firmware Performance Data Table
 * FPGA - [**Field-Programmable Gate Array**](https://en.wikipedia.org/wiki/Field-programmable_gate_array)
 * Framebuffer - The
-  [**framebuffer**](https://en.wikipedia.org/wiki/Framebuffer) is a part
+  [**framebuffer**](http://en.wikipedia.org/wiki/Framebuffer) is a part
   of RAM in a computer which is allocated to hold the graphics
   information for one frame or picture. This information typically
   consists of color values for every pixel on the screen. A framebuffer
@@ -370,15 +358,11 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * FPM - Memory: [**Fast Page Mode**](https://en.wikipedia.org/wiki/Dynamic_random-access_memory#Page_mode_DRAM) - A DRAM standard introduced in 1990.
 * FPU - [**Floating-Point Unit**](https://en.wikipedia.org/wiki/Floating-point_unit)
 * FSB - [**Front-Side Bus**](https://en.wikipedia.org/wiki/Front-side_bus)
-* FSM - Finite State Machine
 * FSP - Intel: Firmware Support Package
-* FSR - Intel: Firmware Status Register
 * FTP - Network Protocol: [**File Transfer Protocol**](https://en.wikipedia.org/wiki/File_Transfer_Protocol)
 * fTPM - Firmware TPM (Trusted Platform Module).  This is a TPM that is
   based in firmware instead of actual hardware.  It typically runs in
   some sort of TEE (Trusted Execution Environment).
-* FWCM Intel: firmware Connection Manager
-* FWID - Firmware Identifier
 
 
 ## G
@@ -399,10 +383,8 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * GMA - Intel: [**Graphics Media
   Accelerator**](https://en.wikipedia.org/wiki/Intel_GMA)
 * GNB - Graphics NorthBridge
-* GND - Power: Ground
 * GNVS - Global Non-Volatile Storage
 * GPD - PCH GPIO in Deep Sleep well (D5 power)
-* GPE - ACPI: General Purpose Event
 * GPI - GPIOs: GPIO Input
 * GPIO - [**General Purpose Input/Output**](https://en.wikipedia.org/wiki/General-purpose_Input/Output) (Pin)
 * GPMR - Intel: General Purpose Memory Range
@@ -414,30 +396,21 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * GPU - [**Graphics Processing Unit**](https://en.wikipedia.org/wiki/Graphics_processing_unit)
 * GSoC - [**Google Summer of Code**](https://en.wikipedia.org/wiki/Google_Summer_of_Code)
 * GSC - Google Security Chip - Typically Cr50/Ti50, though could also refer to the titan chips
-* GSPI - Generic SPI - These are SPI controllers available for general
-  use, not dedicated to flash, for example.
-* GTDT - ACPI: Generic Timer Description Table
-* GTT - [**Graphics Translation Table**](https://en.wikipedia.org/wiki/Graphics_address_remapping_table)
 * GUID - UEFI: [**Globally Unique IDentifier**](https://en.wikipedia.org/wiki/Universally_unique_identifier)
 
 
 ## H
 
-* HBP - Graphics: [**Horizontal Back Porch**](https://en.wikipedia.org/wiki/Horizontal_blanking_interval) In the Horizontal blanking interval, this is the blank area past the end of the scanline
 * HDA - [**High Definition Audio**](https://en.wikipedia.org/wiki/Intel_High_Definition_Audio)
 * HDCP - [**High-bandwidth Digital Content Protection**](https://en.wikipedia.org/wiki/High-bandwidth_Digital_Content_Protection)
 * HDD - Hard Disk Drive
 * HDMI - [**High-Definition Multimedia Interface**](https://en.wikipedia.org/wiki/HDMI)
 * HDR - [**High Dynamic Range**](https://en.wikipedia.org/wiki/High_dynamic_range)
 * HECI - Intel: [**Host Embedded Controller Interface**](https://en.wikipedia.org/wiki/Host_Embedded_Controller_Interface) (Replaced by MEI)
-* HFP - Graphics: [**Horizontal Front Porch**](https://en.wikipedia.org/wiki/Horizontal_blanking_interval) In the Horizontal blanking interval, this is the blank before the start of the next scanline.
 * HID - [**Human Interface
   Device**](https://en.wikipedia.org/wiki/Human_interface_device)
 * HOB - UEFI: Hand-Off Block
-* HPD - Hot-Plug Detect
 * HPET - [**High Precision Event Timer**](https://en.wikipedia.org/wiki/High_Precision_Event_Timer)
-* HSP - AMD: Hardware Security Processor
-* HSPHY - USB: USB3 High-Speed PHY
 * HSTI - Hardware Security Test Interface
 * HSW - Intel: Haswell
 * Hybrid S3 - System Power State:  This is where the operating system
@@ -446,7 +419,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   resume quickly from S3 if the system stays powered, and resume from
   the disk if power is lost.
 * Hypertransport - AMD: The
-  [**Hypertransport**](https://en.wikipedia.org/wiki/Hypertransport) bus
+  [**Hypertransport**](http://en.wikipedia.org/wiki/Hypertransport) bus
   is an older (2001-2017) high-speed electrical interconnection protocol
   specification between CPU, Memory, and (occasionally) peripheral
   devices.  This was originally called the Lightning Data Transport
@@ -467,7 +440,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   - Also known as SenseWire
 * IA - Intel Architecture
 * IA-64 - Intel Itanium 64-bit architecture
-* IAFC - RISC-V: [**RISC-V Base Integer instruction set**](https://en.wikipedia.org/wiki/RISC-V), plus atomic instructions, single precision floating point instructions, and compressed instructions
 * IBB – Initial Boot Block
 * IBV - Independent BIOS Vendor
 * IC - Integrated Circuit
@@ -484,8 +456,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * IF - AMD: [**Infinity
   Fabric**](https://en.wikipedia.org/wiki/HyperTransport#Infinity_Fabric)
   is a superset of AMD's earlier Hypertransport interconnect.
-* IFD - Intel: Intel Flash Descriptor
-* IMAFC - RISC-V: [**RISC-V Base Integer instruction set**](https://en.wikipedia.org/wiki/RISC-V), plus integer multiply & divide, atomic instructions, single precision floating point instructions, and compressed instructions
 * IMC - AMD: Integrated micro-controller - An 8051 microcontroller built
   into some AMD FCHs (Fusion Controller Hubs) and Southbridge chips.
   This never worked well for anything beyond fan control and caused
@@ -497,7 +467,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * IoC - Security: Indicator of Compromise
 * IOC - Intel: I/O Cache
 * IOE - Intel: I/O Expander
-* IOHC - AMD: I/O Hub Controller
 * IOM - Intel: I/O Manager
 * IOMMU - [**I/O Memory Management Unit**](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit)
 * IOMUX - AMD: The I/O Mux block controls how each GPIO is configured.
@@ -520,7 +489,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * IVHD - ACPI: I/O Virtualization Hardware Definition
 * IVMD - ACPI: I/O Virtualization Memory Definition
 * IVRS - I/O Virtualization Reporting Structure
-* IWYU - Include What you Use - A tool to help with include file use
 
 
 ## J
@@ -561,7 +529,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * LAPIC - Local APIC
 * LBA - Logical Block Address
 * LCD - Liquid Crystal Display
-* LCAP - PCIe: Link Capabilities
+* LCAP - PCIe:Link Capabilities
 * LED - Light Emitting Diode
 * LF - Line Feed - The standard Unix EOL (End-of-Line) marker.
 * LGTM - Looks Good To Me
@@ -574,7 +542,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   count**](http://www.intel.com/design/chipsets/industry/lpc.htm) bus
   was a replacement for the ISA bus, created by serializing a number of
   parallel signals to get rid of those connections.
-* LPM - USB: Link Power Management
 * LPT - Line Print Terminal, Local Print Terminal, or Line Printer. -
   The Parallel Port
 * LRU - Least Recently Used - a rule used in operating systems that
@@ -591,21 +558,15 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 
 * M.2 - An interface specification for small peripheral cards.
 * MAC Address - Media Access Control Address
-* MAFS - (eSPI) Master Attached Flash Sharing: Flash components are
-  attached to the controller device and may be accessed by by the
-  peripheral devices through the eSPI flash access channel.
-* MBP - Intel UEFI: ME-to-BIOS Payload
 * MBR - Master Boot Record
 * MCA - [**Machine Check Architecture**](https://en.wikipedia.org/wiki/Machine_Check_Architecture)
 * MCR - Machine Check Registers
-* MCTP - [**Management Component Transport Protocol**](https://en.wikipedia.org/wiki/Management_Component_Transport_Protocol)
 * MCU - Memory Control Unit
 * MCU - [**MicroController
   Unit**](https://en.wikipedia.org/wiki/Microcontroller)
-* MCUPM - Mediatek: MCUPM is a hardware module which is used for MCUSYS Power Management. MCUPM firmware (mcupm.bin) is loaded into MCUPM SRAM at system initialization.
+* MCTP - [**Management Component Transport Protocol**](https://en.wikipedia.org/wiki/Management_Component_Transport_Protocol)
 * MDFIO - Intel: Multi-Die Fabric IO
 * MDN - AMD: Mendocino
-* mDP - Mini DisplayPort connector
 * ME - Intel: Management Engine
 * MEI - Intel: ME Interface (Previously known as HECI)
 * Memory training - the process of finding the best speeds, voltages,
@@ -622,7 +583,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * MKBP - Matrix Keyboard Protocol
 * MMC - [**MultiMedia
   Card**](https://en.wikipedia.org/wiki/MultiMediaCard)
-* MMIO - [**Memory Mapped I/O**](https://en.wikipedia.org/wiki/MMIO)
+* MMIO - [**Memory Mapped I/O**](http://en.wikipedia.org/wiki/MMIO)
   allows peripherals' memory or registers to be accessed directly
   through the memory bus.  When the memory bus size was very small, this
   was initially done by hiding any memory at that address, effectively
@@ -649,23 +610,21 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * MSB - Most Significant Bit
 * MSI - Message Signaled Interrupt
 * MSR - Machine-Specific Register
-* MTS or MT/s - MegaTransfers per second
+* MT/s - MegaTransfers per second
 * MTL - Intel: Meteor Lake
 * MTL - ARM: MHU Transport Layer
-* MTRR - [**Memory Type and Range Register**](https://en.wikipedia.org/wiki/MTRR)
+* MTRR - [**Memory Type and Range Register**](http://en.wikipedia.org/wiki/MTRR)
   allows to set the cache behaviour on memory access in x86. Basically,
   it tells the CPU how to cache certain ranges of memory
   (e.g. write-through, write-combining, write-back...). Memory ranges
   are specified over physical address ranges. In Linux, they are visible
   over `/proc/mtrr` and they can be modified there. For further
   information, see the [**Linux documentation**](https://www.kernel.org/doc/html/v5.19/x86/pat.html).
-* MXM - PCIe: [**Mobile PCI Express Module**](https://en.wikipedia.org/wiki/Mobile_PCI_Express_Module)
 
 
 ## N
 
 * Nack - Negative Acknowledgement
-* NB - North Bridge
 * NBCI - Nvidia: NoteBook Common Interface
 * NC - GPIOs: No Connect
 * NDA - Non-Disclosure Agreement.
@@ -685,7 +644,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * NVME - Non-Volatile Memory Express - An SSD interface that allows
   access to the flash memory through a PCIe bus.
 * NVPCF - Nvidia Platform and Control Framework
-* NVVDD - Nvidia Power: Core voltage
 * NX - No Execute
 
 
@@ -731,23 +689,21 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * PCD - UEFI: Platform Configuration Database
 * PCH - Intel: [**Platform Controller Hub**](https://en.wikipedia.org/wiki/Platform_Controller_Hub)
 * PCI - [**Peripheral Control
-  Interconnect**](https://en.wikipedia.org/wiki/Peripheral_Component_Interconnect)
+  Interconnect**](http://en.wikipedia.org/wiki/Peripheral_Component_Interconnect)
   - Replaced generally by PCIe (PCI Express)
 * PCI Configuration Space - The [**PCI Config
-  space**](https://en.wikipedia.org/wiki/PCI_Configuration_Space) is an
+  space**](http://en.wikipedia.org/wiki/PCI_Configuration_Space) is an
   [address space](https://en.wikipedia.org/wiki/Address_space) for all
   PCI devices.  Originally, this address space was accessed through an
   index/data pair by writing the address that you wanted to read/write
   into the I/O address 0xCF8, then reading or writing I/O Address 0xCFC.
   This has been updated to an MMIO method which increases each PCI
   function's configuration space from 256 bytes to 4K.
-* PCIe - [**PCI Express**](https://en.wikipedia.org/wiki/Pci_express)
+* PCIe - [**PCI Express**](http://en.wikipedia.org/wiki/Pci_express)
 * PCMCIA: Personal Computer Memory Card International Association
 * PCO - AMD: [**Picasso**](https://en.wikichip.org/wiki/amd/cores/picasso)
 * PCR: TPM: Platform Configuration Register
-* PD - GPIOs: Pull-Down - Drives the pin to ground through a resistor.
-  The resistor allows the pin to be set to the reference voltage as
-  needed.
+* PD - GPIOs: Pull-Down - Setting the pin high drives it to the reference voltage.  Setting it low drives it to ground through a resistor.
 * PD - Power Delivery - This is a specification for communicating power
   needs and availability between two devices, typically over USB type C.
 * PEG - PCIe Graphics - A (typically) x16 PCIe slot connected to the CPU
@@ -755,9 +711,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * PEI - UEFI: Pre-EFI Initialization
 * PEIM - UEFI: PEI Module
 * PEP - Intel: Power Engine Plug-in
-* PEXVDD - Nvidia Power: PCIExpress Voltage
-* PHX - AMD: Phoenix SoC
-* PHY - [**PHYsical layer**](https://en.wikipedia.org/wiki/PHY) - The
+* PHY - [**PHYsical layer**](http://en.wikipedia.org/wiki/PHY) - The
   hardware that implements the send/receive functionality of a
   communication protocol.
 * PI - Platform Initialization
@@ -776,7 +730,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * PIT - Generally refers to the 8253/8254 [**Programmable Interval
   Timer**](https://en.wikipedia.org/wiki/Programmable_interval_timer).
 * PLCC - [**Plastic leaded chip
-  carrier**](https://en.wikipedia.org/wiki/Plastic_leaded_chip_carrier)
+  carrier**](http://en.wikipedia.org/wiki/Plastic_leaded_chip_carrier)
 * PLL - [**Phase-Locked
   Loop**](https://en.wikipedia.org/wiki/Phase-locked_loop)
 * PM - Platform Management
@@ -798,21 +752,15 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * POTS - [**Plain Old Telephone
   Service**](https://en.wikipedia.org/wiki/Plain_old_telephone_service)
 * PPI - UEFI: PEIM-to-PEIM Interface
-* PPR - Processor Programming Reference
+* PPR: Processor Programming Reference
 * PPT - AMD: Package Power Tracking
-* PROM - Programmable Read Only Memory
+* PROM: Programmable Read Only Memory
 * Proto - Production Timeline: The first initial production to test key
   concepts.
 * PSE - Page Size Extention
-* PSF - Intel: Primary Sideband Fabric
 * PSP - AMD: Platform Security Processor
 * PSPP - AMD: PCIE Speed Power Policy
-* PSR - Intel: Platform Service Record
-* PSR - Graphics: Panel Self-Refresh - This is a power-savings feature specified in eDP
-* PTT - Intel: Platform Trust Technology - Intel's firmware based TPM.
-* PU - GPIOs: Pull-Up - Drives the pin to reference voltage through a
-  resistor. The resistor allows the signal to still be set to ground
-  when needed.
+* PU - GPIOs: Pull-Up - Setting the pin low drives it to ground.  Setting it high drives it to the reference voltage through a resistor.
 * PVT - Production Timeline: (Production Validation Test
 * PWM - Pulse Width Modulation
 * PXE - Pre-boot Execution Environment
@@ -835,7 +783,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   a set of 3 or 4 GPIOs to allow 8 to 16 different memory chips to be
   used.
 * RAPL - Running Average Power Limit
-* RCB - PCIe: Read Completion Boundary - Sets the address alignment on which a read request may be serviced with multiple completions
 * RCS - [**Revision control
   system**](https://en.wikipedia.org/wiki/Revision_Control_System)
 * Real mode - The original 20-bit addressing mode of the 8086 & 8088
@@ -843,7 +790,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   Segment:Offset index pair.  In 2022, this is still the mode that
   x86-64 processors are in at the reset vector!
 * RDMA - [**Remote Direct Memory
-  Access**](https://en.wikipedia.org/wiki/Remote_Direct_Memory_Access) is
+  Access**](http://en.wikipedia.org/wiki/Remote_Direct_Memory_Access) is
   a concept whereby two or more computers communicate via DMA directly
   from main memory of one system to the main memory of another.
 * RFC - Request for Comment
@@ -856,11 +803,9 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * ROM - Read Only Memory
 * RoT - Root of Trust
 * RPL - Intel: [**Raptor Lake**](https://en.wikipedia.org/wiki/Raptor_Lake)
-* RPP - Intel: Raptor Point PCH
 * RRG - AMD (ATI): Register Reference Guide
 * RSDP - Root System Description Pointer
 * RTC - Real Time Clock
-* RTD3 - Power State: Runtime D3
 * RTFM - Read the Fucking Manual
 * RTOS - Real-Time Operating System
 * RVP - Intel: Reference Validation Platform
@@ -896,11 +841,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   contents of memory.  Any critical processor state is restored.
 * S5 - ACPI System Power State: System is “completely powered off”, but
   still has power going to the board.
-* SAFS - (eSPI) Slave Attached Flash Sharing: Flash is attached to the
-  peripheral device.  Only valid for server platforms.
-* SAGV - Intel: System Agent Geyserville. The original internal name
-  for the feature eventually released as Speedstep which controls the
-  processor voltage and frequencies.
 * SAR - The [**Specific Absorption
   Rate**](https://en.wikipedia.org/wiki/Specific_absorption_rate) is the
   measurement for the amount of Radio Frequency (RF) energy absorbed by
@@ -924,7 +864,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   SAS (Serial Attached SCSI).  The initial version is now often referred
   to as Parallel SCSI.
 * SD - [**Secure Digital**](https://en.wikipedia.org/wiki/SD_card) card
-* SDHCI - SD Host Controller Interface
 * SDRAM - Synchronous DRAM
 * SDLE: AMD: Stardust Dynamic Load Emulator
 * SEEP - Serial EEPROM (Electrically Erasable Programmable Read-Only
@@ -948,7 +887,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * SMBus -  [**System Management
   Bus**](https://en.wikipedia.org/wiki/System_Management_Bus)
   * [http://www.smbus.org/](http://www.smbus.org/)
-* SME - AMD: Secure Memory Encryption
 * SMI - System management interrupt
 * SMM - [**System management
   mode**](https://en.wikipedia.org/wiki/System_Management_Mode)
@@ -962,7 +900,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * SO-DIMM: Small Outline Dual In-Line Memory Module
 * SoC - System on a Chip
 * SOIC - [**Small-Outline Integrated
-  Circuit**](https://en.wikipedia.org/wiki/Small-outline_integrated_circuit)
+  Circuit**](http://en.wikipedia.org/wiki/Small-outline_integrated_circuit)
 * SPD - [**Serial Presence
   Detect**](https://en.wikipedia.org/wiki/Serial_presence_detect)
 * SPI - [**Serial Peripheral
@@ -970,7 +908,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * SPL - AMD: Security Patch Level
 * SPM - Mediatek: System Power Manager
 * SPMI - MIPI: System Power Management Interface
-* SPR - Sapphire Rapids
 * SRAM - Static Random Access Memory
 * SSD - Solid State Drive
 * SSDT - Secondary System Descriptor Table - ACPI table
@@ -987,7 +924,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * SSI-TEB - Physical board format: [**SSI Thin Electronics
   Bay**](https://en.wikipedia.org/wiki/SSI_CEB)
 * SSP - [**Speech Signal Processor**](https://en.wikipedia.org/wiki/Speech_processing)
-* SSPHY - USB: USB3 Super-Speed PHY
 * STAPM - AMD: Skin Temperature Aware Power Management
 * STB - AMD: Smart Trace Buffer
 * SuperIO - The [**Super I/O**](https://en.wikipedia.org/wiki/Super_I/O)
@@ -995,16 +931,13 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   peripherals.  Most common are: A PS/2 Keyboard and mouse port, LPT
   Ports, UARTS, Watchdog Timers, Floppy drive Controllers, GPIOs, or any
   of a number of various other devices.
-* SVC - ARM: Supervisor Call
 * SVI2/3 - Serial VID (Voltage Identification) Interface 2.0 / 3.0
-* SWCM - Intel: Software Connection Manager
 
 
 ## T
 
 * TBT - Thunderbolt
 * TBT - Intel: Turbo Boost Technology
-* tBUF - I2C: The bus free time between a STOP and START condition
 * TCC - Intel: Thermal Control Circuit
 * TCP - Transmission Control Protocol
 * TCPC - Type C Port Controller
@@ -1028,8 +961,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * TOLUM - Top of Low Usable Memory
 * ToM - Top of Memory
 * TPM - Trusted Platform Module
-* TS - TimeStamp
-* TSN - Time-Sensitive Networking
+* TS - TimeStamp -
 * TSC - [**Time Stamp
   Counter**](https://en.wikipedia.org/wiki/Time_Stamp_Counter)
 * TSEG - TOM (Top of Memory) Segment
@@ -1046,9 +978,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * uCode - [**Microcode**](https://en.wikipedia.org/wiki/Microcode)
 * UDK - UEFI: UEFI Development Kit
 * UDP - User Datagram Protocol
-* UDMA - ATA: [**Ultra DMA**](https://en.wikipedia.org/wiki/UDMA) - The fastest transfer mode for ATA Hard Drives
 * UEFI - Unified Extensible Firmware Interface
-* UFC - User Facing Camera
 * UFP - USB: Upstream Facing Port
 * UFS - Universal Flash storage
 * UHCI - USB: [**Universal Host Controller
@@ -1064,7 +994,6 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * UPS - Uninterruptible Power Supply
 * USART - Universal Synchronous/Asynchronous Receiver/Transmitter
 * USB - Universal Serial Bus
-* USF - Intel: Universal Scalable Firmware
 
 
 ## V
@@ -1072,8 +1001,7 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * VBIOS - Video BIOS
 * VBNV - Vboot Non-Volatile storage
 * VBT - [**Video BIOS
-  Table**](https://www.kernel.org/doc/html/latest/gpu/i915.html#video-bios-table-vbt)
-* VDDQ Memory/Power: The supply voltage to the output buffers of a memory chip.
+  Table**](https://01.org/linuxgraphics/gfx-docs/drm/ch04s02.html#id-1.4.3.4.16)
 * VESA - Video Electronics Standards Association
 * VGA: Video Graphics Array
 * VID: Vendor Identifier
@@ -1081,17 +1009,12 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 * VLB - VESA Local Bus
 * VOIP - Voice over IP
 * Voodoo mode - a silly name for Big Real mode.
-* VMX - Intel: CPU flag for Hardware Virtualization
 * VPD - Vital Product Data
 * VPN - Virtual Private Network
-* VPU - Intel: Versatile Processor Unit
 * VR - Voltage Regulator
 * VRAM - Video Random Access Memory
-* VREF Memory/Power: Reference voltage for the input lines of a chip that determines the voltage level at which the threshold between a logical 1 and a logical 0 occurs. Usually 1/2 VDDQ.
 * VRM - Voltage Regulator Module
 * VT-d - Intel: Virtualization Technology for Directed I/O
-* VTT Memory/Power: Tracking Termination Voltage
-* vUART - Virtual UART
 
 
 ## W
@@ -1105,11 +1028,9 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   devices that open 360 degrees, or on the outside of the cover.  For
   tablets, it's on the the side away from the screen.
 * WDT - [**WatchDog Timer**](https://en.wikipedia.org/wiki/Watchdog_timer)
-* WFC - World Facing Camera
 * WLAN - Wireless LAN (Local Area Network)
 * WWAN - Telecommunication: Wireless WAN (Wide Area Network)
 * WP - Cache policy: [**Write-Protected**](https://en.wikipedia.org/wiki/Cache_%28computing%29)
-* WPT - Intel: Wildcat Point - PCH for Broadwell
 * WO - Write-only
 * WOL - [**Wake-on-LAN**](https://en.wikipedia.org/wiki/Wake-on-LAN)
 * WT - Cache Policy: [**Write Through**](https://en.wikipedia.org/wiki/Cache_%28computing%29)
@@ -1130,9 +1051,8 @@ Spec](https://uefi.org/specifications) for details, or run the tool
   supporting 1.x, 2.0, and 3.x devices.
 
 
-## Y
 
-* YCC - Color Space: [**YCbCr**](https://en.wikipedia.org/wiki/YCbCr) - A family of color spaces used in video
+## Y
 
 
 ## Z
@@ -1141,8 +1061,4 @@ Spec](https://uefi.org/specifications) for details, or run the tool
 
 
 ## References:
-```{toctree}
-:maxdepth: 1
-
-AMD Glossary of terms <https://www.amd.com/system/files/documents/glossary-of-terms-20220505-for-web.pdf>
-```
+* [AMD Glossary of terms](https://www.amd.com/system/files/documents/glossary-of-terms-20220505-for-web.pdf)

Documentation/arch/index.md

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

Documentation/arch/x86/index.md

@@ -2,14 +2,12 @@
 
 This section contains documentation about coreboot on x86 architecture.
 
-```{toctree}
-:maxdepth: 1
-
-x86 PAE support <pae.md>
-```
+* [x86 PAE support](pae.md)
 
 ## State of x86_64 support
-Some SOCs now support 64bit mode. Search for HAVE_X86_64_SUPPORT in Kconfig.
+At the moment there's only experimental x86_64 support.
+The `emulation/qemu-i440fx` and `emulation/qemu-q35` boards do support
+*ARCH_RAMSTAGE_X86_64* , *ARCH_POSTCAR_X86_64* and *ARCH_ROMSTAGE_X86_64*.
 
 In order to add support for x86_64 the following assumptions were made:
 * The CPU supports long mode
@@ -17,6 +15,7 @@ In order to add support for x86_64 the following assumptions were made:
 * All code that is to be run must be below 4GiB in physical memory
 * The high dword of pointers is always zero
 * The reference implementation is qemu
+* The CPU supports 1GiB hugepages
 * x86 payloads are loaded below 4GiB in physical memory and are jumped
   to in *protected mode*
 
@@ -44,12 +43,8 @@ Basic support for x86_64 has been implemented for QEMU mainboard target.
 
 ## Reference implementation
 The reference implementation is
-```{toctree}
-:maxdepth: 1
-
-QEMU i440fx <../../mainboard/emulation/qemu-i440fx.md>
-QEMU Q35 <../../mainboard/emulation/qemu-q35.md>
-```
+* [QEMU i440fx](../../mainboard/emulation/qemu-i440fx.md)
+* [QEMU Q35](../../mainboard/emulation/qemu-q35.md)
 
 ## TODO
 * Identity map memory above 4GiB in ramstage
@@ -59,6 +54,7 @@ QEMU Q35 <../../mainboard/emulation/qemu-q35.md>
 1. Fine grained page tables for SMM:
    * Must not have execute and write permissions for the same page.
    * Must allow only that TSEG pages can be marked executable
+   * Must reside in SMRAM
 2. Support 64bit PCI BARs above 4GiB
 3. Place and run code above 4GiB
 
@@ -66,10 +62,13 @@ QEMU Q35 <../../mainboard/emulation/qemu-q35.md>
 * Fix compilation errors
 * Test how well CAR works with x86_64 and paging
 * Improve mode switches
+* Test libgfxinit / VGA Option ROMs / FSP
 
-## Known problems on real hardware
+## Known bugs on real hardware
 
-Running VGA rom directly fails. Yabel works fine though.
+According to Intel x86_64 mode hasn't been validated in CAR environments.
+Until now it could be verified on various Intel platforms and no issues have
+been found.
 
 ## Known bugs on KVM enabled qemu
 

Documentation/community/code_of_conduct.md

@@ -95,17 +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.
 
-## 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;

Documentation/community/forums.md

@@ -14,7 +14,7 @@ read its
 ## Real time chat
 
 We also have a real time chat room on [IRC](ircs://irc.libera.chat/#coreboot),
-also bridged to [Matrix](https://matrix.to/#/#coreboot:matrix.org) and a
+also bridged to [Matrix](https://matrix.to/#/#coreboot:libera.chat) and a
 [Discord](https://discord.gg/JqT8NM5Zbg) presence. You can also find us on
 [OSF Slack](https://osfw.slack.com/), which has channels on many open source
 firmware related topics. Slack requires that people come from specific domains

Documentation/community/index.md

@@ -1,10 +1,6 @@
 # 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>
-```
+* [Code of Conduct](code_of_conduct.md)
+* [Language style](language_style.md)
+* [Community forums](forums.md)
+* [coreboot at conferences](conferences.md)

Documentation/conf.py

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

Documentation/contributing/coding_style.md

@@ -6,14 +6,14 @@ kernel coding style. In fact, most of this document has been copied from
 the [Linux kernel coding style](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/4.Coding.rst)
 
 The guidelines in this file should be seen as a strong suggestion, and
-should overrule personal preference. They may be ignored in individual
-instances when there are good practical reasons to do so, and reviewers
-are in agreement.
+should overrule personal preference. But they may be ignored in
+individual instances when there are good practical reasons to do so, and
+reviewers are in agreement.
 
 Any style questions that are not mentioned in here should be decided
 between the author and reviewers on a case-by-case basis. When modifying
 existing files, authors should try to match the prevalent style in that
-file -- otherwise, they should generally match similar existing files in
+file -- otherwise, they should try to match similar existing files in
 coreboot.
 
 Bulk style changes to existing code ("cleanup patches") should avoid
@@ -24,8 +24,7 @@ be honored. (Note that `checkpatch.pl` is not part of this style guide,
 and neither is `clang-format`. These tools can be useful to find
 potential issues or simplify formatting in new submissions, but they
 were not designed to directly match this guide and may have false
-positives. They should not be bulk-applied to change existing code
-except in cases where they directly match the style guide.)
+positives. They should not be bulk-applied to change existing code.)
 
 ## Indentation
 
@@ -43,8 +42,7 @@ Now, some people will claim that having 8-character indentations makes
 the code move too far to the right, and makes it hard to read on a
 80-character terminal screen. The answer to that is that if you need
 more than 3 levels of indentation, you're screwed anyway, and should
-fix your program.  Note that coreboot has expanded the 80 character
-limit to 96 characters to allow for modern wider screens.
+fix your program.
 
 In short, 8-char indents make things easier to read, and have the added
 benefit of warning you when you're nesting your functions too deep.
@@ -89,9 +87,7 @@ Outside of comments, documentation and except in Kconfig, spaces are
 never used for indentation, and the above example is deliberately
 broken.
 
-Get a decent editor and don't leave whitespace at the end of lines. This
-will actually keep the patch from being tested in the CI, so patches
-with ending whitespace cannot be merged.
+Get a decent editor and don't leave whitespace at the end of lines.
 
 ## Breaking long lines and strings
 
@@ -507,14 +503,18 @@ comments to note or warn about something particularly clever (or ugly),
 but try to avoid excess. Instead, put the comments at the head of the
 function, telling people what it does, and possibly WHY it does it.
 
-coreboot style for comments is the C89 "/* ... */" style. You may also
-use C99-style "// ..." comments for single-line comments.
+When commenting the kernel API functions, please use the kernel-doc
+format. See the files Documentation/kernel-doc-nano-HOWTO.txt and
+scripts/kernel-doc for details.
+
+coreboot style for comments is the C89 "/* ... */" style. You may
+use C99-style "// ..." comments.
 
 The preferred style for *short* (multi-line) comments is:
 
 ```c
 /* This is the preferred style for short multi-line
-   comments in the coreboot source code.
+   comments in the Linux kernel source code.
    Please use it consistently. */
 ```
 
@@ -523,7 +523,7 @@ The preferred style for *long* (multi-line) comments is:
 ```c
 /*
  * This is the preferred style for multi-line
- * comments in the coreboot source code.
+ * comments in the Linux kernel source code.
  * Please use it consistently.
  *
  * Description:  A column of asterisks on the left side,
@@ -578,8 +578,7 @@ To do the latter, you can stick the following in your .emacs file:
 ```
 
 This will make emacs go better with the kernel coding style for C files
-below ~/src/linux-trees.  Obviously, this should be updated to match
-your own paths for coreboot.
+below ~/src/linux-trees.
 
 But even if you fail in getting emacs to do sane formatting, not
 everything is lost: use "indent".
@@ -627,6 +626,38 @@ config ADFS_FS_RW
 For full documentation on the configuration files, see the file
 Documentation/kbuild/kconfig-language.txt.
 
+Data structures
+---------------
+
+Data structures that have visibility outside the single-threaded
+environment they are created and destroyed in should always have
+reference counts. In the kernel, garbage collection doesn't exist (and
+outside the kernel garbage collection is slow and inefficient), which
+means that you absolutely _have_ to reference count all your uses.
+
+Reference counting means that you can avoid locking, and allows multiple
+users to have access to the data structure in parallel - and not having
+to worry about the structure suddenly going away from under them just
+because they slept or did something else for a while.
+
+Note that locking is _not_ a replacement for reference counting.
+Locking is used to keep data structures coherent, while reference
+counting is a memory management technique. Usually both are needed, and
+they are not to be confused with each other.
+
+Many data structures can indeed have two levels of reference counting,
+when there are users of different "classes". The subclass count counts
+the number of subclass users, and decrements the global count just once
+when the subclass count goes to zero.
+
+Examples of this kind of "multi-level-reference-counting" can be found
+in memory management ("struct mm_struct": mm_users and mm_count),
+and in filesystem code ("struct super_block": s_count and
+s_active).
+
+Remember: if another thread can find your data structure, and you don't
+have a reference count on it, you almost certainly have a bug.
+
 Macros, Enums and RTL
 ---------------------
 
@@ -696,19 +727,35 @@ The cpp manual deals with macros exhaustively. The gcc internals manual
 also covers RTL which is used frequently with assembly language in the
 kernel.
 
-Printing coreboot messages
+Printing kernel messages
 ------------------------
 
-coreboot developers like to be seen as literate. Do mind the spelling of
-coreboot messages to make a good impression. Do not use crippled words
+Kernel developers like to be seen as literate. Do mind the spelling of
+kernel messages to make a good impression. Do not use crippled words
 like "dont"; use "do not" or "don't" instead. Make the messages
 concise, clear, and unambiguous.
 
-coreboot messages do not have to be terminated with a period.
+Kernel messages do not have to be terminated with a period.
 
 Printing numbers in parentheses (%d) adds no value and should be
 avoided.
 
+There are a number of driver model diagnostic macros in
+<linux/device.h> which you should use to make sure messages are
+matched to the right device and driver, and are tagged with the right
+level: dev_err(), dev_warn(), dev_info(), and so forth. For messages
+that aren't associated with a particular device, <linux/printk.h>
+defines pr_debug() and pr_info().
+
+Coming up with good debugging messages can be quite a challenge; and
+once you have them, they can be a huge help for remote troubleshooting.
+Such messages should be compiled out when the DEBUG symbol is not
+defined (that is, by default they are not included). When you use
+dev_dbg() or pr_debug(), that's automatic. Many subsystems have
+Kconfig options to turn on -DDEBUG. A related convention uses
+VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled
+by DEBUG.
+
 Allocating memory
 -----------------
 
@@ -745,7 +792,12 @@ The inline disease
 There appears to be a common misperception that gcc has a magic "make
 me faster" speedup option called "inline". While the use of inlines
 can be appropriate (for example as a means of replacing macros, see
-Chapter 12), it very often is not.
+Chapter 12), it very often is not. Abundant use of the inline keyword
+leads to a much bigger kernel, which in turn slows the system as a whole
+down, due to a bigger icache footprint for the CPU and simply because
+there is less memory available for the pagecache. Just think about it; a
+pagecache miss causes a disk seek, which easily takes 5 milliseconds.
+There are a LOT of cpu cycles that can go into these 5 milliseconds.
 
 A reasonable rule of thumb is to not put inline at functions that have
 more than 3 lines of code in them. An exception to this rule are the
@@ -808,7 +860,7 @@ eDP display panel encounters an I2C error, it should print a "cannot read EDID"
 message and return an error code. The calling display initialization function
 knows that without the EDID there is no way to initialize the display correctly,
 so it will also immediately return with an error code without running its
-remaining code that would initialize the SoC's display controller. Execution
+remaining code that would initialize the SoC's display controller. Exeuction
 returns further up the function stack to the mainboard initialization code
 which continues booting despite the failed display initialization, since
 display functionality is non-essential to the system. (Code is encouraged but
@@ -871,7 +923,7 @@ in the same directory that is not part of a normal include path gets included
 .c files should keep all C code wrapped in `#ifndef __ASSEMBLER__` blocks,
 including includes to other headers that don't follow that provision. Where a
 specific include order is required for technical reasons, it should be clearly
-documented with comments. This should not be the norm.
+documented with comments.
 
 Files should generally include every header they need a definition from
 directly (and not include any unnecessary extra headers). Excepted from
@@ -1006,29 +1058,6 @@ This rule only applies to explicit GCC extensions listed in the
 should never rely on incidental GCC translation behavior that is not
 explicitly documented as a feature and could change at any moment.
 
-Refactoring
------------
-Because refactoring existing code can add bugs to tested code, any
-refactors should be done only with serious consideration. Refactoring
-for style differences should only be done if the existing style
-conflicts with a documented coreboot guideline. If you believe that the
-style should be modified, the pros and cons can be discussed on the
-mailing list and in the coreboot leadership meeting.
-
-Similarly, the original author should be respected. Changing working
-code simply because of a stylistic disagreement is *prohibited*. This is
-not saying that refactors that are objectively better (simpler, faster,
-easier to understand) are not allowed, but there has to be a definite
-improvement, not simply stylistic changes.
-
-Basically, when refactoring code, there should be a clear benefit to
-the project and codebase. The reviewers and submitters get to make the
-call on how to interpret this.
-
-When refactoring, adding unit tests to verify that the post-change
-functionality matches or improves upon pre-change functionality is
-encouraged.
-
 References
 ----------
 

Documentation/contributing/gerrit_guidelines.md

@@ -9,7 +9,7 @@ friction in the community.
 
 Note that as with many rules, there are exceptions. Some have been noted
 in the 'More Detail' section. If you feel there is an exception not listed
-here, please discuss it in the mailing list to get this document updated.
+here, please discuss it in the mailing list to get this document  updated.
 Don't just assume that it's okay, even if someone on IRC says it is.
 
 
@@ -41,7 +41,7 @@ project you're submitting the changes to. If you’re submitting code that
 you wrote that might be owned by your employer, make sure that your
 employer is aware and you are authorized to submit the code. For
 clarification, see the Developer's Certificate of Origin in the coreboot
-[Signed-off-by policy](#sign-off-procedure).
+[Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure).
 
 * In general, patches should remain open for review for at least 24 hours
 since the last significant modification to the change. The purpose is to
@@ -127,54 +127,6 @@ those platforms. While it would be nice to update any other platforms, you
 must at least provide a path that will allow other platforms to continue
 working.
 
-Sign-off Procedure
-------------------
-The coreboot project employs a sign-off procedure similar to what is
-used by the Linux kernel. Each gerrit commit requires a sign-off line
-saying that the contributed code abides by the Developer's certificate
-of origin, below.
-```text
-Signed-off-by: Random J Developer <random@developer.example.org>
-```
-
-Using '-s' with 'git commit' will automatically add a Signed-off-by line
-to your commit message.  Patches without a Signed-off-by should not be
-pushed to gerrit, and will be rejected by coreboot's CI system.
-
-You must use a known identity in the Signed-off-by line. Anonymous
-contributions cannot be committed! This can be anything sufficient to
-identify and contact the source of a contribution, such as your name or
-an established alias/nickname. Refer to [this LKML thread] and the
-[SCO-Linux disputes] for the rationale behind the DCO.
-
-Developer's Certificate of Origin 1.1
-
-> By making a contribution to this project, I certify that:
->
-> (a) The contribution was created in whole or in part by me and I have
-> the right to submit it under the open source license indicated in the
-> file; or
->
-> (b) The contribution is based upon previous work that, to the best of
-> my knowledge, is covered under an appropriate open source license and
-> I have the right under that license to submit that work with
-> modifications, whether created in whole or in part by me, under the
-> same open source license (unless I am permitted to submit under a
-> different license), as indicated in the file; or
->
-> (c) The contribution was provided directly to me by some other person
-> who certified (a), (b) or (c) and I have not modified it; and
->
-> (d) In the case of each of (a), (b), or (c), I understand and agree
-> that this project and the contribution are public and that a record of
-> the contribution (including all personal information I submit with it,
-> including my sign-off) is maintained indefinitely and may be
-> redistributed consistent with this project or the open source license
-> indicated in the file.
-
-Note: The [Developer's Certificate of Origin 1.1] is licensed under the
-terms of the [Creative Commons Attribution-ShareAlike 2.5 License].
-
 
 Recommendations for gerrit activity
 -----------------------------------
@@ -221,10 +173,7 @@ This helps verify that the patch train won’t tie up the jenkins builders
 for no reason if there are failing patches in the train. For running
 parallel builds, you can specify the number of cores to use by setting the
 the CPUS environment variable. Example:
-
-```Bash
-make what-jenkins-does CPUS=8
-```
+        make what-jenkins-does CPUS=8
 
 * Use a topic when pushing a train of patches. This groups the commits
 together so people can easily see the connection at the top level of
@@ -232,10 +181,7 @@ gerrit. Topics can be set for individual patches in gerrit by going into
 the patch and clicking on the icon next to the topic line. Topics can also
 be set when you push the patches into gerrit. For example, to push a set of
 commits with the i915-kernel-x60 set, use the command:
-
-```Bash
-git push origin HEAD:refs/for/main%topic=i915-kernel-x60
-```
+        git push origin HEAD:refs/for/master%topic=i915-kernel-x60
 
 * If one of your patches isn't ready to be merged, make sure it's obvious
 that you don't feel it's ready for merge yet. The preferred way to show
@@ -245,10 +191,7 @@ Examples of this are "WIP: title" or "[NEEDS_TEST]: title".  Another way to
 mark the patch as not ready would be to give it a -1 or -2 review, but
 isn't as obvious as the commit message. These patches can also be pushed with
 the wip flag:
-
-```Bash
-git push origin HEAD:refs/for/main%wip
-```
+	git push origin HEAD:refs/for/master%wip
 
 * When pushing patches that are not for submission, these should be marked
 as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as
@@ -257,16 +200,10 @@ 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
-```
+        git push origin HEAD:refs/for/master%private
 
 * Multiple push options can be combined:
-
-```Bash
-git push origin HEAD:refs/for/main%private,wip,topic=experiment
-```
+        git push origin HEAD:refs/for/master%private,wip,topic=experiment
 
 * Respond to anyone who has taken the time to review your patches, even if
 it's just to say that you disagree. While it may seem annoying to address a
@@ -292,7 +229,7 @@ changed.
 helps others and shows that these mainboards are currently being
 maintained. At some point, boards that are not up to date in the
 board-status repo will probably end up getting removed from the coreboot
-main branch.
+master branch.
 
 * Abandon patches that are no longer useful, or that you don’t intend to
 keep working on to get submitted.
@@ -340,15 +277,13 @@ 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/gitconfig/rebase.sh` can be used to help automate this.
+        Commit-Id:
+        Change-Id:
+        Signed-off-by:
+        Reviewed-on:
+        Tested-by:
+        Reviewed-by:
+The script 'util/gitconfig/rebase.sh' can be used to help automate this.
 Other tags such as 'Commit-Queue' can simply be removed.
 
 * Check if there's documentation that needs to be updated to remain current
@@ -395,8 +330,8 @@ Gerrit user roles
 There are a few relevant roles a user can have on Gerrit:
 
 - The anonymous user can check out source code.
-- A registered user can also comment and give "+1" code reviews.
-- A reviewer can give "-1" and "+2" code reviews.
+- A registered user can also comment and give "+1" and "-1" code reviews.
+- A reviewer can also give "+2" code reviews.
 - A core developer can also give "-2" (that is, blocking) code reviews
   and submit changes.
 
@@ -434,7 +369,3 @@ Requests for clarification and suggestions for updates to these guidelines
 should be sent to the coreboot mailing list at <coreboot@coreboot.org>.
 
 [ready changes]: https://review.coreboot.org/q/age:1d+project:coreboot+status:open+is:mergeable+label:All-Comments-Resolved%253Dok+label:Code-Review%253D2+-label:Code-Review%253C0+label:Verified%253D1+-label:Verified-1
-[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

Documentation/contributing/gsoc.md

@@ -1,16 +1,5 @@
 # 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
 
@@ -19,6 +8,9 @@ please have a look at our [community forums] and reach out to us. Working closel
 with the community is highly encouraged, as we've seen that our most successful
 contributors are generally very involved.
 
+Felix Singer, David Hendricks and Martin Roth are the coreboot GSoC admins for
+2022. Please feel free to reach out to them directly if you have any questions.
+
 
 ## Why work on coreboot for GSoC?
 
@@ -59,8 +51,6 @@ contributors are generally very involved.
 
   * [Glossary][GSoC Glossary]
 
-  * [Organization Admin Tips][GSoC Organization Admin Tips]
-
 
 ## Contributor requirements & commitments
 
@@ -101,7 +91,7 @@ amount of spare time. If this is not the case, then you should not apply.
       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
+      Check the [easy project list][Project ideas] or ask for simple tasks on
       the [mailing list] or on our other [community forums] if you need ideas.
 
 
@@ -283,4 +273,3 @@ questions.
 [GSoC FAQ]: https://developers.google.com/open-source/gsoc/faq
 [GSoC Rules]: https://summerofcode.withgoogle.com/rules
 [GSoC Glossary]: https://developers.google.com/open-source/gsoc/resources/glossary
-[GSoC Organization Admin Tips]: https://developers.google.com/open-source/gsoc/help/oa-tips

Documentation/contributing/index.md

@@ -1,11 +1,7 @@
 # Contributing
 
-```{toctree}
-:maxdepth: 1
-
-Coding Style <coding_style.md>
-Gerrit Guidelines <gerrit_guidelines.md>
-Project Ideas <project_ideas.md>
-Documentation Ideas <documentation_ideas.md>
-Google Summer of Code <gsoc.md>
-```
+* [Coding Style](coding_style.md)
+* [Gerrit Guidelines](gerrit_guidelines.md)
+* [Project Ideas](project_ideas.md)
+* [Documentation Ideas](documentation_ideas.md)
+* [Google Summer of Code](gsoc.md)

Documentation/contributing/project_ideas.md

@@ -20,12 +20,12 @@ 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
+## Easy projects
 
 This is a collection of tasks which don't require deep knowledge on
 coreboot itself. If you are a beginner and want to get familiar with the
 the project and the code base, or if you just want to get your hands
-dirty with some small tasks, then these are for you.
+dirty with some easy tasks, then these are for you.
 
   * Resolve static analysis issues reported by [scan-build] and
     [Coverity scan]. More details on the page for
@@ -36,7 +36,7 @@ dirty with some small tasks, then these are for you.
 [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
+[Linter issues]: https://qa.coreboot.org/job/untested-coreboot-files/lastSuccessfulBuild/artifact/lint.txt
 
 ## Provide toolchain binaries
 Our crossgcc subproject provides a uniform compiler environment for
@@ -63,6 +63,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
@@ -87,7 +88,7 @@ across architectures.
 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.
+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 +130,7 @@ their bug reports.
   going on from the resulting logs.
 
 ### Mentors
+* Patrick Georgi <patrick@georgi.software>
 
 ## Extend Ghidra to support analysis of firmware images
 [Ghidra](https://ghidra-sre.org) is a recently released cross-platform

Documentation/corebootBuildingGuide.tex

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

Documentation/distributions.md

@@ -8,6 +8,15 @@ and those providing after-market firmware to extend the usefulness of devices.
 
 ## Hardware shipping with coreboot
 
+### NovaCustom laptops
+
+[NovaCustom](https://configurelaptop.eu/) sells configurable laptops with
+[Dasharo](https://dasharo.com/) coreboot based firmware on board, maintained by
+[3mdeb](https://3mdeb.com/). NovaCustom offers full GNU/Linux and Microsoft
+Windows compatibility. NovaCustom ensures security updates via fwupd for 5 years
+and the firmware is equipped with important security features such as measured
+boot, verified boot, TPM integration and UEFI Secure Boot.
+
 ### ChromeOS Devices
 
 All ChromeOS devices ([Chromebooks](https://chromebookdb.com/), Chromeboxes,
@@ -17,25 +26,6 @@ running on the Embedded Controller (EC) – a small microcontroller which provid
 functions like battery management, keyboard support, and sensor interfacing –
 is open source as well.
 
-### Nitrokey
-
-[Nitrokey](https://nitrokey.com) is a german IT security hardware vendor which
-offers a range of laptops, PCs, HSMs, and networking devices with coreboot and
-[Dasharo](https://dasharo.com/). The devices come with neutralized Intel
-Management Engine (ME) and with pre-installed [Heads](http://osresearch.net) or
-EDK2 payload providing measured boot and verified boot protection. For
-additional security the systems can be physically sealed and pictures of those
-sealings are sent via encrypted email.
-
-### NovaCustom laptops
-
-[NovaCustom](https://novacustom.com) sells configurable laptops with
-[Dasharo](https://dasharo.com/) coreboot based firmware on board, maintained by
-[3mdeb](https://3mdeb.com/). NovaCustom offers full GNU/Linux and Microsoft
-Windows compatibility. NovaCustom ensures security updates via fwupd for 5 years
-and the firmware is equipped with important security features such as measured
-boot, verified boot, TPM integration and UEFI Secure Boot.
-
 ### PC Engines APUs
 
 [PC Engines](https://pcengines.ch) designs and sells embedded PC hardware that
@@ -43,23 +33,6 @@ ships with coreboot and support upstream maintenance for the devices through a
 third party, [3mdeb](https://3mdeb.com). They provide current and tested
 firmware binaries on [GitHub](https://pcengines.github.io).
 
-### 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
@@ -74,8 +47,23 @@ servers. Some models are sold with [System76 Open
 Firmware](https://github.com/system76/firmware-open), an open source
 distribution of coreboot, edk2, and System76 firmware applications.
 
+### Purism
+
+[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
+security; part of that effort is to minimize the amount of proprietary and/or
+binary code. Their laptops ship with a blob-free OS and coreboot firmware
+with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
+
 ## After-market firmware
 
+### Libreboot
+
+[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.
+
+
 ### Dasharo
 
 [Dasharo](https://dasharo.com/) is an open-source based firmware distribution
@@ -83,8 +71,18 @@ focusing on clean and simple code, long-term maintenance, transparent
 validation, privacy-respecting implementation, liberty for the owners, and
 trustworthiness for all.
 
-Contributions are welcome,
-[this document](https://docs.dasharo.com/ways-you-can-help-us/).
+
+### 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 :)
 
 ### Heads
 
@@ -99,25 +97,6 @@ Heads is not just another Linux distribution – it combines physical hardening
 of specific hardware platforms and flash security features with custom coreboot
 firmware and a Linux boot loader in ROM.
 
-### Libreboot
-
-[Libreboot](https://libreboot.org) is a downstream coreboot distribution that
-provides ready-made firmware images for supported devices: those which can be
-built entirely from source code. Their copy of the coreboot repository is
-therefore stripped of all devices that require binary components to boot.
-
-### MrChromebox
-
-[MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
-images for the vast majority of x86-based Chromebooks and Chromeboxes, using
-edk2 as the payload to provide a modern UEFI bootloader. Why replace
-coreboot with coreboot? Mr Chromebox's images are built using upstream
-coreboot (vs Google's older, static tree/branch), include many features and
-fixes not found in the stock firmware, and offer much broader OS compatibility
-(i.e., they run Windows as well as Linux). They also offer updated CPU
-microcode, as well as firmware updates for the device's embedded controller
-(EC). This firmware "takes the training wheels off" your ChromeOS device :)
-
 ### Skulls
 
 [Skulls](https://github.com/merge/skulls) provides firmware images for

Documentation/drivers/index.md

@@ -8,14 +8,10 @@ For details on how to connect device drivers to a mainboard, see [Driver Devicet
 
 Some of the drivers currently available include:
 
-```{toctree}
-:maxdepth: 1
-
-Intel DPTF <dptf.md>
-IPMI KCS <ipmi_kcs.md>
-SMMSTORE <smmstore.md>
-SMMSTOREv2 <smmstorev2.md>
-SoundWire <soundwire.md>
-USB4 Retimer <retimer.md>
-CBFS SMBIOS hooks <cbfs_smbios.md>
-```
+* [Intel DPTF](dptf.md)
+* [IPMI KCS](ipmi_kcs.md)
+* [SMMSTORE](smmstore.md)
+* [SMMSTOREv2](smmstorev2.md)
+* [SoundWire](soundwire.md)
+* [USB4 Retimer](retimer.md)
+* [CBFS SMBIOS hooks](cbfs_smbios.md)

Documentation/drivers/smmstore.md

@@ -128,11 +128,7 @@ data or modify the currently running kernel.*
 
 ## External links
 
-```{toctree}
-:maxdepth: 1
-
-A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI <https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf>
-```
+* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
 Note, this differs significantly from coreboot's implementation.
 
 [SMM]: ../security/smm.md

Documentation/drivers/smmstorev2.md

@@ -124,9 +124,25 @@ additional calling arguments are passed via `%ebx`.
 **NOTE**: The size of the struct entries are in the native word size of
 smihandler. This means 32 bits in almost all cases.
 
-#### - SMMSTORE_CMD_INIT_DEPRECATED = 4
+#### - SMMSTORE_CMD_INIT = 4
 
-Unused, returns SMMSTORE_REG_UNSUPPORTED.
+This installs the communication buffer to use and thus enables the
+SMMSTORE handler. This command can only be executed once and is done
+by the firmware. Calling this function at runtime has no effect.
+
+The additional parameter buffer `%ebx` contains a pointer to the
+following struct:
+
+```C
+struct smmstore_params_init {
+	uint32_t com_buffer;
+	uint32_t com_buffer_size;
+} __packed;
+```
+
+INPUT:
+- `com_buffer`: Physical address of the communication buffer (CBMEM)
+- `com_buffer_size`: Size in bytes of the communication buffer
 
 #### - SMMSTORE_CMD_RAW_READ = 5
 
@@ -199,11 +215,7 @@ running kernel.
 
 ## External links
 
-```{toctree}
-:maxdepth: 1
-
-A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI <https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf>
-```
+* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
 Note that this differs significantly from coreboot's implementation.
 
 [SMM]: ../security/smm.md

Documentation/external_docs.md

@@ -17,128 +17,62 @@ Please add any helpful or informational links and sections as you see fit.
   * [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)
-```{toctree}
-:maxdepth: 1
-
-Boot Guard and PSB have user-hostile defaults <https://mjg59.dreamwidth.org/58424.html>
-```
+* [Boot Guard and PSB have user-hostile defaults](https://mjg59.dreamwidth.org/58424.html)
 
 
 ## General Information
 
-```{toctree}
-:maxdepth: 1
+* [OS Dev](https://wiki.osdev.org/Categorized_Main_Page)
+* [Interface BUS](http://www.interfacebus.com/)
+* Open course material for a variety of topics such as assembly, firmware,
+  security, debugging, and more.
+  * [Open Security Training](https://opensecuritytraining.info/Training.html),
+  * [Open Security Training 2](https://p.ost2.fyi/)
 
-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:
-
-```{toctree}
-:maxdepth: 1
-
-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
 
-```{toctree}
-:maxdepth: 1
-
-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>
-```
+* [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
 
-```{toctree}
-:maxdepth: 1
-
-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>
-```
+* [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
 
-```{toctree}
-:maxdepth: 1
-
-Intel Boot Guard <https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/intel_boot_guard>
-```
+* [Intel Boot Guard](https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/intel_boot_guard)
 
 
 ## Hardware information
 
-```{toctree}
-:maxdepth: 1
-
-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>
-```
+* [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
-```{toctree}
-:maxdepth: 1
-
-eMMC <https://www.jedec.org/)  - JEDEC - (LOGIN REQUIRED>
-```
+* [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
-```{toctree}
-:maxdepth: 1
-
-I3C <https://www.mipi.org/specifications/i3c-sensor-specification) - MIPI Alliance (LOGIN REQUIRED>
-Memory <https://www.jedec.org/)  - JEDEC - (LOGIN REQUIRED>
-```
+* [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
-```{toctree}
-:maxdepth: 1
-
-PCI / PCIe / M.2 <https://pcisig.com/specifications) -  PCI-SIG - (LOGIN REQUIRED>
-```
+* [PCI / PCIe / M.2](https://pcisig.com/specifications) -  PCI-SIG - (LOGIN REQUIRED)
 * [Power Delivery](https://www.usb.org/documents) - USB Implementers Forum
-```{toctree}
-:maxdepth: 1
-
-SATA <https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN REQUIRED>
-```
+* [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
@@ -157,7 +91,6 @@ SATA <https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN RE
   * [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)
@@ -177,9 +110,5 @@ SATA <https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN RE
 
 ## Infrastructure software
 
-```{toctree}
-:maxdepth: 1
-
-Kconfig <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>
-GNU Make <https://www.gnu.org/software/make/manual/>
-```
+* [Kconfig](https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html)
+* [GNU Make](https://www.gnu.org/software/make/manual/)

Documentation/getting_started/build_system.md

@@ -7,10 +7,10 @@ to the point of providing its own custom language.
 The overhead of learning this new syntax is (hopefully) offset by its lower
 complexity.
 
-The build system is defined in the toplevel `Makefile` and `toolchain.mk`
+The build system is defined in the toplevel `Makefile` and `toolchain.inc`
 and is supposed to be generic (and is in fact used with a number of other
 projects).  Project specific configuration should reside in files called
-`Makefile.mk`.
+`Makefile.inc`.
 
 In general, the build system provides a number of "classes" that describe
 various parts of the build. These cover the various build targets in coreboot
@@ -36,7 +36,7 @@ TODO: explain how to create new classes and how to evaluate them.
 ### subdirs
 `subdirs` contains subdirectories (relative to the current directory) that
 should also be handled by the build system. The build system expects these
-directories to contain a file called `Makefile.mk`.
+directories to contain a file called `Makefile.inc`.
 
 Subdirectories are not read at the point where the `subdirs` statement
 resides but later, after the current directory is handled (and potentially
@@ -62,23 +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.
-
-```{eval-rst}
-See also :doc:`../tutorial/managing_local_additions`.
-```
-
 #### 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
@@ -100,4 +83,4 @@ The default implementation just returns `COREBOOT` (the default region) for
 all files.
 
 vboot provides its own implementation of `regions-for-file` that can be used
-as reference in `src/vboot/Makefile.mk`.
+as reference in `src/vboot/Makefile.inc`.

Documentation/getting_started/devicetree.md

@@ -79,7 +79,7 @@ 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.
+See [Driver Devicetree Entries](drivers/dt_entries.md) for more info.
 
 ## Notes
 

Documentation/getting_started/faq.md

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

Documentation/getting_started/gpio.md

@@ -167,7 +167,7 @@ could cause catastrophic failures, up to and including your mainboard!
 As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register
 supports four different types of GPIO reset as:
 
-```{eval-rst}
+```eval_rst
 +------------------------+----------------+-------------+-------------+
 |                        |                |         PAD Reset ?       |
 + PAD Reset Config       + Platform Reset +-------------+-------------+

Documentation/getting_started/index.md

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

Documentation/getting_started/kconfig.md

@@ -11,12 +11,8 @@ configuration front end in coreboot today.
 
 The official Kconfig source and documentation is kept at kernel.org:
 
-```{toctree}
-:maxdepth: 1
-
-Kconfig source <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig>
-Kconfig Language Documentation <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>
-```
+- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig)
+- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt)
 
 The advantage to using Kconfig is that it allows users to easily select the
 high level features of the project to be enabled or disabled at build time.
@@ -73,6 +69,9 @@ These variables are typically set in the makefiles or on the make command line.
 These variables were added to Kconfig specifically for coreboot and are not
 included in the Linux version.
 
+- KCONFIG_STRICT=value. Define to enable warnings as errors.   This is enabled
+  in coreboot, and should not be changed.
+
 - KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file
   (build/config.h). This is enabled in coreboot, and should not be changed.
 
@@ -103,9 +102,6 @@ included in the Linux version.
 - KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”.
   coreboot sets this to $(obj)/config.
 
-- KCONFIG_WERROR=value. Define to enable warnings as errors. This is enabled
-  in coreboot, and should not be changed.
-
 #### Used only for ‘make menuconfig’
 - MENUCONFIG_MODE=single_menu.  Set to "single_menu" to enable.  All other
   values disable the option.  This makes submenus appear below the menu option
@@ -200,9 +196,9 @@ values to be set based on other values.
   visible in the front end.
 
 
-### Keywords
+## Keywords
 
-#### bool
+### bool
 
 The 'bool' keyword assigns a boolean type to a symbol. The allowable values for
 a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt
@@ -238,7 +234,7 @@ bool \[prompt\] \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### choice
+### choice
 
 This creates a selection list of one or more boolean symbols. For bools, only
 one of the symbols can be selected, and one will be be forced to be selected,
@@ -301,7 +297,7 @@ choice \[symbol\]
 
 --------------------------------------------------------------------------------
 
-#### comment
+### comment
 
 This keyword defines a line of text that is displayed to the user in the
 configuration frontend and is additionally written to the output files.
@@ -326,7 +322,7 @@ comment &lt;prompt&gt;
 
 --------------------------------------------------------------------------------
 
-#### config
+### config
 
 This is the keyword that starts a block defining a Kconfig symbol. The symbol
 modifiers follow the 'config' statement.
@@ -363,7 +359,7 @@ config &lt;symbol&gt;
 
 --------------------------------------------------------------------------------
 
-#### default
+### default
 
 The ‘default’ keyword assigns a value to a symbol in the case where no preset
 value exists, i.e. the symbol is not present and assigned in .config.  If there
@@ -403,7 +399,7 @@ default &lt;expr&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### def_bool
+### def_bool
 
 ‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to
 boolean. It lets you set the type and default value at the same time, instead
@@ -437,7 +433,7 @@ def_bool &lt;expr&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### depends on
+### depends on
 
 This defines a dependency for a menu entry, including symbols and comments.  It
 behaves the same as surrounding the menu entry with an if/endif block.  If the
@@ -466,28 +462,28 @@ depends on &lt;expr&gt;
 
 --------------------------------------------------------------------------------
 
-#### endchoice
+### endchoice
 
 This ends a choice block. See the 'choice' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-#### endif
+### endif
 
 This ends a block started by the 'if' keyword. See the 'if' keyword for more
 information and an example.
 
 --------------------------------------------------------------------------------
 
-#### endmenu
+### endmenu
 
 This ends a menu block. See the 'menu' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-#### help
+### help
 
 The 'help' keyword defines the subsequent block of text as help for a config or
 choice block. The help block is started by the 'help' keyword on a line by
@@ -519,7 +515,7 @@ help &lt;help text&gt;
 
 --------------------------------------------------------------------------------
 
-#### hex
+### hex
 
 This is another symbol type specifier, specifying an unsigned integer value
 formatted as hexadecimal.
@@ -555,7 +551,7 @@ hex &lt;expr&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### if
+### if
 
 The 'if' keyword is overloaded, used in two different ways. The first definition
 enables and disables various other keywords, and follows the other keyword
@@ -596,7 +592,7 @@ endif
 
 --------------------------------------------------------------------------------
 
-#### int
+### int
 
 A type setting keyword, defines a symbol as an integer, accepting only signed
 numeric values.  The values can be further restricted with the ‘range’ keyword.
@@ -632,7 +628,7 @@ int &lt;expr&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### mainmenu
+### mainmenu
 
 The 'mainmenu' keyword sets the title or title bar of the configuration front
   end, depending on how the configuration program decides to use it. It can only
@@ -652,7 +648,7 @@ mainmenu "coreboot configuration"
 
 --------------------------------------------------------------------------------
 
-#### menu
+### menu
 
 The 'menu' and 'endmenu' keywords tell the configuration front end that the
 enclosed statements are part of a group of related pieces.
@@ -699,7 +695,7 @@ endmenu
 
 --------------------------------------------------------------------------------
 
-#### prompt
+### prompt
 
 The 'prompt' keyword sets the text displayed for a config symbol or choice in
 configuration front end.
@@ -752,7 +748,7 @@ prompt &lt;prompt&gt; \[if &lt;expr&gt;\]
             prompt "Prompt value 2"
 --------------------------------------------------------------------------------
 
-#### range
+### range
 
 This sets the allowable minimum and maximum entries for hex or int type config
 symbols.
@@ -774,7 +770,7 @@ range &lt;symbol&gt; &lt;symbol&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### select
+### select
 
 The ‘select’ keyword is used within a bool type config block.  In coreboot (and
 other projects that don't use modules), the 'select' keyword can force an
@@ -818,7 +814,7 @@ select &lt;symbol&gt; \[if &lt;expr&gt;\]
 
 --------------------------------------------------------------------------------
 
-#### source
+### source
 
 The 'source' keyword functions much the same as an 'include' statement in c.
 This pulls one or more files into Kconfig at the location of the 'source'
@@ -877,7 +873,7 @@ statements that generate a list of all the platform names:
 
 --------------------------------------------------------------------------------
 
-#### string
+### string
 
 The last of the symbol type assignment keywords. 'string' allows a text value to
 be entered.
@@ -923,7 +919,7 @@ keyword later. See the prompt keyword for more notes.
 
 
 
-### Keywords not used in coreboot at the time of writing:
+## Keywords not used in coreboot at the time of writing:
 
 - allnoconfig_y:
 - defconfig_list
@@ -948,7 +944,7 @@ statements:
     #define SYMBOL NAME XXX
 
 
-#### Symbol types:
+##### Symbol types:
 - bool, int, and hex types -  Every symbol of one of these types created in the
   Kconfig tree is defined.  It doesn’t matter whether they’re in an if/endif
   block, or have a ‘depends on’ statement - they ALL end up being defined in
@@ -967,7 +963,7 @@ variable.  This is not set in coreboot, which uses the default CONFIG_ prefix
 for all of its symbols.
 
 The coreboot makefile forces the config.h file to be included into all coreboot
-C files. This is done in Makefile.mk on the compiler command line using the
+C files. This is done in Makefile.inc on the compiler command line using the
 “-include $(obj)/config.h” command line option.
 
 Example of various symbol types in the config.h file:
@@ -1164,23 +1160,27 @@ saved .config file. As always, a 'select' statement overrides any specified
 - coreboot has added the glob operator '*' for the 'source' keyword.
 - coreboot’s Kconfig always defines variables except for strings. In other
   Kconfig implementations, bools set to false/0/no are not defined.
+- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to
+  error out if there are any issues in the Kconfig files.  In the Linux kernel,
+  Kconfig will generate a warning, but will still output an updated .config or
+  config.h file.
 
 
 ## Kconfig Editor Highlighting
 
-### vim:
+#### vim:
 
 vim has syntax highlighting for Kconfig built in (or at least as a part of
 vim-common), but most editors do not.
 
 
-### ultraedit:
+#### ultraedit:
 
 https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew
 
 
 
-### atom:
+#### atom:
 
 https://github.com/martinlroth/language-kconfig
 

Documentation/getting_started/writing_documentation.md

@@ -99,7 +99,7 @@ To reference documents use the TOC tree or inline RST code.
 Under Sphinx markdown tables are not supported. Therefore you can use following
 code block to write tables in reStructuredText and embed them into the markdown:
 
-    ```{eval-rst}
+    ```eval_rst
     +------------+------------+-----------+
     | Header 1   | Header 2   | Header 3  |
     +============+============+===========+
@@ -144,7 +144,7 @@ you'll see the following warning:
 You can import CSV files and let sphinx automatically convert them to human
 readable tables, using the following reStructuredText snipped:
 
-    ```{eval-rst}
+    ```eval_rst
     .. csv-table::
        :header: "Key", "Value"
        :file: keyvalues.csv

Documentation/gfx/display-panel.md

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

Documentation/index.md

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

Documentation/infrastructure/admin.md

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

Documentation/infrastructure/builders.md

@@ -24,7 +24,8 @@ issues.
 
 Currently active Jenkins admins:
 *   Patrick Georgi:
-    *   Email: [patrick@coreboot.org](mailto:patrick@coreboot.org)
+    *   Email: [patrick@georgi-clan.de](mailto:patrick@georgi-clan.de)
+    *   IRC: pgeorgi
 *   Martin Roth:
     *   Email: [gaumless@gmail.com](mailto:gaumless@gmail.com)
     *   IRC: martinr
@@ -73,7 +74,7 @@ These times are taken from the week of Feb 21 - Feb 28, 2022
 
 There are a number of builds handled by the coreboot jenkins builders,
 for a number of different projects - coreboot, flashrom, memtest86+,
-em100, etc.  Many of these have builders for their current main branch
+em100, etc.  Many of these have builders for their current master branch
 as well as Gerrit and [Coverity](coverity.md) builds.
 
 
@@ -90,22 +91,14 @@ machines.  These tasks run overnight in the US timezones.
 You can see all the builds in the main jenkins interface:
 [https://qa.coreboot.org/](https://qa.coreboot.org/)
 
-Most of the time on the builders is taken up by the coreboot main and
+Most of the time on the builders is taken up by the coreboot master and
 coreboot gerrit builds.
 
-```{toctree}
-:maxdepth: 1
-
-coreboot gerrit build <https://qa.coreboot.org/job/coreboot-gerrit/>
-```
+* [coreboot gerrit build](https://qa.coreboot.org/job/coreboot-gerrit/)
 ([Time trend](https://qa.coreboot.org/job/coreboot-gerrit/buildTimeTrend))
 
 
-```{toctree}
-:maxdepth: 1
-
-coreboot main build <https://qa.coreboot.org/job/coreboot/>
-```
+* [coreboot master build](https://qa.coreboot.org/job/coreboot/)
  ([Time trend](https://qa.coreboot.org/job/coreboot/buildTimeTrend))
 
 

Documentation/infrastructure/index.md

@@ -4,17 +4,9 @@ This section contains documentation about our infrastructure
 
 ## Services
 
-```{toctree}
-:maxdepth: 1
+* [Project services](services.md)
 
-Project services <services.md>
-Administrator's handbook <admin.md>
-```
 
 ## Jenkins builders and builds
-```{toctree}
-:maxdepth: 1
-
-Setting up Jenkins build machines <builders.md>
-Coverity Scan integration <coverity.md>
-```
+* [Setting up Jenkins build machines](builders.md)
+* [Coverity Scan integration](coverity.md)

Documentation/lib/flashmap.md

@@ -73,7 +73,7 @@ compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot
 utility folder that can be used to generate final firmware images (i.e.
 `coreboot.rom`) formatted by Flashmap.
 
-The FMD implementation is in coreboot `util/cbfstool` folder. Here's an
+The FMD implementation is in coreboot `utils/cbfstool` folder. Here's an
 informal language description:
 
 ```

Documentation/lib/fw_config.md

@@ -106,8 +106,8 @@ protection)* with the `ectool` command in a ChromeOS environment.
 For more information on the firmware configuration field on ChromeOS devices see the Chromium
 documentation for [Firmware Config][1] and [Board Info][2].
 
-[1]: http://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/firmware_config.md
-[2]: http://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md
+[1]: http://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/firmware_config.md
+[2]: http://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/cros_board_info.md
 
 ## Firmware Configuration Table
 

Documentation/lib/index.md

@@ -3,11 +3,7 @@
 This section contains documentation about coreboot internal technical
 information and libraries.
 
-```{toctree}
-:maxdepth: 1
-
-Flashmap and Flashmap Descriptor <flashmap.md>
-ABI data consumption <abi-data-consumption.md>
-Timestamps <timestamp.md>
-Firmware Configuration Interface <fw_config.md>
-```
+- [Flashmap and Flashmap Descriptor](flashmap.md)
+- [ABI data consumption](abi-data-consumption.md)
+- [Timestamps](timestamp.md)
+- [Firmware Configuration Interface](fw_config.md)

Documentation/lib/payloads/fit.md

@@ -180,5 +180,5 @@ The generated file includes a compressed initrd **initramfs.cpio.xz**, which
 will be decompressed by the Linux kernel, a compressed kernel **Image.lzma**,
 which will be decompressed by the FIT loader and an uncompressed devicetree blob.
 
-[uImage.FIT]: https://github.com/u-boot/u-boot/blob/master/doc/usage/fit/howto.rst
+[uImage.FIT]: https://raw.githubusercontent.com/u-boot/u-boot/master/doc/uImage.FIT/howto.txt
 [U-Boot]: https://www.denx.de/wiki/U-Boot

Documentation/lib/payloads/index.md

@@ -8,8 +8,4 @@ selected mainboard.
 
 ## FIT
 
-```{toctree}
-:maxdepth: 1
-
-uImage.FIT support <fit.md>
-```
+- [uImage.FIT support](fit.md)

Documentation/mainboard/acer/g43t-am3.md

@@ -5,7 +5,7 @@ Acer models Aspire M3800, Aspire M5800 and possibly more.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | Intel G43 (called x4x in coreboot code)          |
 +------------------+--------------------------------------------------+
@@ -69,7 +69,7 @@ Tests were done with SeaBIOS 1.14.0 and slackware64-live from 2019-07-12
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +-------------------+---------------------+
 | Type              | Value               |
 +===================+=====================+
@@ -122,7 +122,7 @@ $ sudo flashrom \
   -w coreboot.rom
 ```
 
-```{eval-rst}
+```eval_rst
 In addition to the information here, please see the
 :doc:`../../tutorial/flashing_firmware/index`.
 ```

Documentation/mainboard/amd/pademelon/pademelon.md

@@ -33,7 +33,7 @@ Three items are marked in this picture
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+--------------------+
 | Type                | Value              |
 +=====================+====================+
@@ -53,7 +53,7 @@ Three items are marked in this picture
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +---------------+------------------------------+
 | Fan control   | Using fintek F81803A         |
 +---------------+------------------------------+
@@ -63,7 +63,7 @@ Three items are marked in this picture
 
 ## Description of pictures within this document
 
-```{eval-rst}
+```eval_rst
 +----------------------------+----------------------------------------+
 |pademelon.jpg               | Motherboard with components identified |
 +----------------------------+----------------------------------------+

Documentation/mainboard/asrock/h110m-dvs.md

@@ -11,7 +11,7 @@ Intel company provides [Firmware Support Package (2.0)](../../soc/intel/fsp/inde
 
 FSP Information:
 
-```{eval-rst}
+```eval_rst
 +-----------------------------+-------------------+-------------------+
 | FSP Project Name            | Directory         | Specification     |
 +-----------------------------+-------------------+-------------------+
@@ -114,7 +114,7 @@ facing towards the bottom of the board.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | CPU              | Intel Skylake/Kaby Lake (LGA1151)                |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asrock/h77pro4-m.md

@@ -5,7 +5,7 @@ Bridge and Ivy Bridge CPUs.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+
@@ -45,9 +45,7 @@ Tests were done with SeaBIOS 1.14.0 and slackware64-live from 2019-07-12
 - Rear eSATA connector (multiplexed with one ASM1061 port)
 - Gigabit Ethernet
 - Console output on the serial port
-- EDK II (MrChromebox's fork, at origin/uefipayload_202207) to boot
-Windows 10 (22H2) and Linux (5.19.17) via GRUB 2
-- SeaBIOS 1.16.1 to boot Windows 10 (needs VGA BIOS) and Linux via
+- SeaBIOS 1.14.0 and 1.15.0 to boot Windows 10 (needs VGA BIOS) and Linux via
 extlinux
 - Internal flashing with flashrom-1.2, see
 [Internal Programming](#internal-programming)
@@ -71,7 +69,7 @@ extlinux
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+
@@ -115,7 +113,7 @@ $ sudo flashrom --noverify-all --ifd -i bios -p internal -w coreboot.rom
 The use of `--noverify-all` is required since the Management Engine
 region is not readable even by the host.
 
-```{eval-rst}
+```eval_rst
 In addition to the information here, please see the
 :doc:`../../tutorial/flashing_firmware/index`.
 ```

Documentation/mainboard/asrock/h81m-hds.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASRock H81M-HDS].
 
 ## Required proprietary blobs
 
-```{eval-rst}
+```eval_rst
 Please see :doc:`../../northbridge/intel/haswell/mrc.bin`.
 ```
 
@@ -75,7 +75,7 @@ facing towards the bottom of the board.
   in coreboot. The `coretemp` driver can still be used for accurate CPU
   temperature readings from an OS.
 
-```{eval-rst}
+```eval_rst
 Please also see :doc:`../../northbridge/intel/haswell/known-issues`.
 ```
 
@@ -111,7 +111,7 @@ Please also see :doc:`../../northbridge/intel/haswell/known-issues`.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/haswell/index`     |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/a88xm-e.md

@@ -14,7 +14,7 @@ and their GPU is [Sea Islands] (GCN2-based).
 
 A10 Richland is recommended for the best performance and working IOMMU.
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | A88XM-E          |                                                  |
 +------------------+--------------------------------------------------+
@@ -36,7 +36,7 @@ A10 Richland is recommended for the best performance and working IOMMU.
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+

Documentation/mainboard/asus/f2a85-m.md

@@ -15,7 +15,7 @@ Both "Trinity" and "Richland" desktop processing units are working,
 the CPU architecture in these CPUs/APUs is [Piledriver],
 and their GPU is [TeraScale 3] (VLIW4-based).
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | F2A85-M          |                                                  |
 +------------------+--------------------------------------------------+
@@ -35,7 +35,7 @@ and their GPU is [TeraScale 3] (VLIW4-based).
 +------------------+--------------------------------------------------+
 ```
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | F2A85-M LE       |                                                  |
 +------------------+--------------------------------------------------+
@@ -55,7 +55,7 @@ and their GPU is [TeraScale 3] (VLIW4-based).
 +------------------+--------------------------------------------------+
 ```
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | F2A85-M PRO      |                                                  |
 +------------------+--------------------------------------------------+
@@ -77,7 +77,7 @@ and their GPU is [TeraScale 3] (VLIW4-based).
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+

Documentation/mainboard/asus/p2b-ls.md

@@ -1,108 +0,0 @@
-# ASUS P2B-LS
-
-This page describes how to run coreboot on the ASUS P2B-LS mainboard.
-
-## Variants
-
-- P2B-LS
-- P2B-L (Same circuit board with SCSI components omitted)
-- P2B-S (Same circuit board with ethernet components omitted)
-
-## Flashing coreboot
-
-```{eval-rst}
-+---------------------+---------------------------+
-| Type                | Value                     |
-+=====================+===========================+
-| Model               | SST 39SF020A (or similar) |
-+---------------------+---------------------------+
-| Protocol            | Parallel                  |
-+---------------------+---------------------------+
-| Size                | 256 KiB                   |
-+---------------------+---------------------------+
-| Package             | DIP-32                    |
-+---------------------+---------------------------+
-| Socketed            | yes                       |
-+---------------------+---------------------------+
-| Write protection    | no                        |
-+---------------------+---------------------------+
-| Dual BIOS feature   | no                        |
-+---------------------+---------------------------+
-| Internal flashing   | yes                       |
-+---------------------+---------------------------+
-```
-
-[flashrom] works out of the box since 0.9.2.
-Because of deficiency in vendor firmware, user needs to override the laptop
-warning as prompted. Once coreboot is in place there will be no further issue.
-
-### CPU microcode considerations
-
-By default, this board includes microcode updates for 5 families of Intel CPUs
-because of the wide variety of CPUs the board supports, directly or with an
-adapter. These take up a third of the total flash space leaving only 20kB free
-in the final cbfs image. It may be necessary to build a custom microcode update
-file by manually concatenating files in 3rdparty/intel-microcode/intel-ucode
-for only CPU models that the board will actually be run with.
-
-## Working
-
-- Slot 1 and Socket 370 CPUs and their L1/L2 caches
-- PS/2 keyboard with SeaBIOS (See [Known issues])
-- IDE hard drives
-- Ethernet (-LS, -L; Intel 82558)
-- SCSI (-LS, -S; Adaptec AIC7890)
-- USB
-- ISA add-on cards
-- PCI add-on cards
-- AGP graphics card
-- Floppy
-- Serial ports 1 and 2
-- Reboot
-- Soft off
-
-## Known issues
-
-- PS/2 keyboard may not be usable until Linux has completely booted.
-  With SeaBIOS as payload, setting keyboard initialization timeout to
-  500ms may fix the issue.
-
-- i440BX does not support 256Mbit RAM modules. If installed, coreboot
-  will attempt to initialize them at half their capacity anyway
-  whereas vendor firmware will not boot at all.
-
-- ECC memory can be used, but ECC support is still pending.
-
-- Termination is enabled for all SCSI ports (if equipped). Support to
-  disable termination is pending. Note that the SCSI-68 port is
-  always terminated, even with vendor firmware.
-
-## Untested
-
-- Parallel port
-- EDO memory
-- Infrared
-- PC speaker
-
-## Not working
-
-- S3 suspend to RAM
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| Northbridge      | Intel I440BX                                     |
-+------------------+--------------------------------------------------+
-| Southbridge      | i82371eb                                         |
-+------------------+--------------------------------------------------+
-| CPU              | P6 family for Slot 1 and Socket 370              |
-|                  | (all models from model_63x to model_6bx)         |
-+------------------+--------------------------------------------------+
-| Super I/O        | winbond/w83977tf                                 |
-+------------------+--------------------------------------------------+
-```
-
-## Extra resources
-
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/asus/p3b-f.md

@@ -1,106 +0,0 @@
-# ASUS P3B-F
-
-This page describes how to run coreboot on the ASUS P3B-F mainboard.
-
-## Flashing coreboot
-
-```{eval-rst}
-+---------------------+---------------------------+
-| Type                | Value                     |
-+=====================+===========================+
-| Model               | SST 39SF020A (or similar) |
-+---------------------+---------------------------+
-| Protocol            | Parallel                  |
-+---------------------+---------------------------+
-| Size                | 256 KiB                   |
-+---------------------+---------------------------+
-| Package             | DIP-32                    |
-+---------------------+---------------------------+
-| Socketed            | yes                       |
-+---------------------+---------------------------+
-| Write protection    | See below                 |
-+---------------------+---------------------------+
-| Internal flashing   | yes                       |
-+---------------------+---------------------------+
-```
-
-flashrom supports this mainboard since commit c7e9a6e15153684672bbadd1fc6baed8247ba0f6.
-If you are using older versions of flashrom, below has to be done (with ACPI disabled!)
-before flashrom can detect the flash chip:
-
-```bash
-  #  rmmod w83781d
-  #  modprobe i2c-dev
-  #  i2cset 0 0x48 0x80 0x80
-```
-
-Upon power up, flash chip is inaccessible until flashrom has been run once.
-Since flashrom does not support reversing board enabling steps,
-once it detects the flash chip, there will be no write protection until
-the next power cycle.
-
-### CPU microcode considerations
-
-By default, this board includes microcode updates for 5 families of Intel CPUs
-because of the wide variety of CPUs the board supports, directly or with an
-adapter. These take up a third of the total flash space leaving only 20kB free
-in the final cbfs image. It may be necessary to build a custom microcode update
-file by manually concatenating files in 3rdparty/intel-microcode/intel-ucode
-for only CPU models that the board will actually be run with.
-
-## Working
-
-- Slot 1 and Socket 370 CPUs and their L1/L2 caches
-- PS/2 keyboard with SeaBIOS (See [Known issues])
-- IDE hard drives
-- USB
-- PCI add-on cards
-- AGP graphics cards
-- Serial ports 1 and 2
-- Reboot
-
-## Known issues
-
-- PS/2 keyboard may not be usable until Linux has completely booted. With SeaBIOS
-  as payload, setting keyboard initialization timeout to 2500ms may help.
-
-- The coreboot+SeaBIOS combination boots so quickly some IDE hard drives are not
-  yet ready by the time SeaBIOS attempts to boot from them.
-
-- i440BX does not support 256Mbit RAM modules. If installed, coreboot
-  will attempt to initialize them at half their capacity anyway
-  whereas vendor firmware will not boot at all.
-
-- ECC memory can be used, but ECC support is still pending.
-
-## Untested
-
-- Floppy
-- Parallel port
-- EDO memory
-- ECC memory
-- Infrared
-- PC speaker
-
-## Not working
-
-- ACPI (Support is currently [under gerrit review](https://review.coreboot.org/c/coreboot/+/41098))
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| Northbridge      | Intel I440BX                                     |
-+------------------+--------------------------------------------------+
-| Southbridge      | i82371eb                                         |
-+------------------+--------------------------------------------------+
-| CPU              | P6 family for Slot 1 and Socket 370              |
-|                  | (all models from model_63x to model_6bx)         |
-+------------------+--------------------------------------------------+
-| Super I/O        | winbond/w83977tf                                 |
-+------------------+--------------------------------------------------+
-```
-
-## Extra resources
-
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/asus/p5q.md

@@ -32,7 +32,7 @@ This page describes how to run coreboot on the [ASUS P5Q] desktop board.
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +-------------------+----------------+
 | Type              | Value          |
 +===================+================+
@@ -56,7 +56,7 @@ You can flash coreboot into your motherboard using [this guide].
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+---------------------------------------------------+
 | Northbridge      | Intel P45 (called x4x in coreboot code)           |
 +------------------+---------------------------------------------------+

Documentation/mainboard/asus/p8c_ws.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8H77-V].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+----------------+
 | Type                | Value          |
 +=====================+================+
@@ -69,7 +69,7 @@ flash externally.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/p8h61-m_lx.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8H61-M LX].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+
@@ -84,7 +84,7 @@ region is not readable even by the host.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/p8h61-m_pro.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8H61-M Pro].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+
@@ -78,7 +78,7 @@ region is not readable even by the host.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/p8h77-v.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8H77-V].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+----------------+
 | Type                | Value          |
 +=====================+================+
@@ -56,7 +56,7 @@ work. The flash chip is socketed, so it's easy to remove and reflash.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/p8z77-m.md

@@ -1,137 +0,0 @@
-# ASUS P8Z77-M
-
-This page describes how to run coreboot on the [ASUS P8Z77-M].
-
-## Flashing coreboot
-
-```{eval-rst}
-+---------------------+----------------+
-| Type                | Value          |
-+=====================+================+
-| Model               | W25Q64FVA1Q    |
-+---------------------+----------------+
-| Size                | 8 MiB          |
-+---------------------+----------------+
-| Package             | DIP-8          |
-+---------------------+----------------+
-| Socketed            | yes            |
-+---------------------+----------------+
-| Write protection    | yes            |
-+---------------------+----------------+
-| Dual BIOS feature   | no             |
-+---------------------+----------------+
-| Internal flashing   | yes            |
-+---------------------+----------------+
-```
-
-The flash chip is located between the blue SATA ports.
-
-The main SPI flash cannot be written internally because Asus disables BIOSWE and
-enables ``BLE/SMM_BWP`` flags in ``BIOS_CNTL`` for their latest bioses.
-To install coreboot for the first time, the flash chip must be removed and
-flashed with an external programmer; flashing in-circuit doesn't work.
-The flash chip is socketed, so it's easy to remove and reflash.
-
-## Working
-
-- All USB2 ports (mouse, keyboard and thumb drive)
-- USB3 ports on rear (Boots SystemRescue 6.0.3 off a Kingston DataTraveler G4 8GB)
-- Gigabit Ethernet (RTL8111F)
-- SATA3, SATA2 (all ports, hot-swap not tested)
-       (Blue SATA2)  (Blue SATA2)  (White SATA3)
-        port 5        port 3        port 1
-        port 6        port 4        port 2
-
-- CPU Temp sensors and hardware monitor (some values don't make sense)
-- Native and MRC memory initialization
-  (please see [Native raminit compatibility] and [MRC memory compatibility])
-
-- Integrated graphics with both libgfxinit and the Intel Video BIOS OpROM
-  (VGA/DVI-D/HDMI tested and working)
-- 16x PCIe GPU in PCIe-16x/4x slots (tested using nVidia Quadro 600 under SystemRescue 6.0.3
-  (Arch based))
-- Serial port
-- PCI slot
-  Rockwell HSF 56k PCI modem, Sound Blaster Live! CT4780 (cards detected, not function tested)
-  Promise SATA150 TX2plus (R/W OK to connected IDE hard drive, OpRom loaded, cannot boot from
-  SeaBIOS)
-- S3 suspend from Linux
-- 2-channel analog audio (WAV playback by mplayer via back panel line out port)
-- Windows 10 with libgfxinit high resolution framebuffer and VBT
-
-## Known issues
-
-- If you use MRC raminit, the NVRAM variable gfx_uma_size may be ignored as IGP's UMA could
-  be reconfigured by the blob.
-
-- If SeaBIOS is used for payload with libgfxinit, it must be brought in via coreboot's config.
-  Otherwise integrated graphics would fail with a black screen.
-
-- PCI POST card is not functional because the PCI bridge early init is not yet done.
-
-- The black PCIEX16_2 slot, although can physically fit an x16, only has physical contacts for
-  an x8, and is electrically an x4 only.
-
-## Untested
-
-- Wake-on-LAN
-- USB3 on header
-- TPM header
-- EHCI debugging (Debug port is on the 5-pin side of USB2_910 header)
-- HDMI and S/PDIF audio out
-
-## Not working
-
-- PS/2 keyboard or mouse
-- 4 and 6 channel analog audio out: Rear left and right audio is a muted
-  copy of front left and right audio, and the other two channels are silent.
-
-## Native (and MRC) raminit compatibility
-
-- OCZ OCZ3G1600LVAM 2x2GB kit works at DDR3-1066 instead of DDR3-1600.
-
-- GSkill F3-1600C9D-16GRSL 2x8GB SODIMM kit on adapter boots, but is highly unstable
-  with obvious pattern of bit errors during memtest86+ runs.
-
-- Samsung PC3-10600U 2x2GB kit works at full rated speed.
-
-- Kingston KTH9600B-4G 2x4GB kit works at full rated speed.
-
-## Extra onboard buttons
-
-The board has two onboard buttons, and each has a related LED nearby.
-What controls the LEDs and what the buttons control are unknown,
-therefore they currently do nothing under coreboot.
-
-- BIOS_FLBK
-  OEM firmware uses this button to facilitate a simple update mechanism
-  via a USB drive plugged into the bottom USB port of the USB/LAN stack.
-
-- MemOK!
-  OEM firmware uses this button for memory tuning related to overclocking.
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6779D                                 |
-+------------------+--------------------------------------------------+
-| EC               | None                                             |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-## Extra resources
-
-- [Flash chip datasheet][W25Q64FVA1Q]
-
-[ASUS P8Z77-M]: https://www.asus.com/Motherboards/P8Z77M/
-[W25Q64FVA1Q]: https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/asus/p8z77-m_pro.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8Z77-M PRO]
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+----------------+
 | Type                | Value          |
 +=====================+================+
@@ -143,7 +143,7 @@ easy to remove and reflash.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/p8z77-v.md

@@ -4,7 +4,7 @@ This page describes how to run coreboot on the [ASUS P8Z77-V].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+----------------+
 | Type                | Value          |
 +=====================+================+
@@ -86,7 +86,7 @@ See [Asus Wi-Fi Go! v1].
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/asus/wifigo_v1.md

@@ -8,7 +8,7 @@ through a proprietary 16-1 pin connector.
 I managed to grope the most pinout of the proprietary connector.
 See [Mini PCIe pinout] for more info.
 
-```{eval-rst}
+```eval_rst
 +------------+----------+-----------+------------+----------+-----------+
 | WIFIGO Pin | Usage    | mPCIe pin | WIFIGO Pin | Usage    | mPCIe pin |
 +============+==========+===========+============+==========+===========+

Documentation/mainboard/cavium/cn8100_sff_evb.md

@@ -17,7 +17,7 @@
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+----------------+
 | Type                | Value          |
 +=====================+================+
@@ -58,7 +58,7 @@
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +---------------+----------------------------------------+
 | SoC           | :doc:`../../soc/cavium/cn81xx/index`   |
 +---------------+----------------------------------------+

Documentation/mainboard/clevo/n130wu/index.md

@@ -2,7 +2,7 @@
 
 ## Hardware
 ### Technology
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------+
 | CPU              | Intel i7-8550U                 |
 +------------------+--------------------------------+
@@ -15,7 +15,7 @@
 ```
 
 ### Flash chip
-```{eval-rst}
+```eval_rst
 +---------------------+-----------------+
 | Type                | Value           |
 +=====================+=================+

Documentation/mainboard/dell/e7240.md

@@ -1,83 +0,0 @@
-# Dell Latitude E7240
-
-This page is about the notebook [Dell Latitude E7240].
-
-## Release status
-
-Dell Latitude E7240 was released in 2013 and is now end of life.
-It can be bought from a secondhand market like Taobao or eBay.
-
-## Required proprietary blobs
-
-The following blobs are required to operate the hardware:
-1. mrc.bin
-2. Intel ME firmware
-
-Memory reference code in mrc.bin is used to initialize the Haswell platform.
-You need this blob to build a working coreboot image. Please read
-[mrc.bin](../../northbridge/intel/haswell/mrc.bin) for instructions on
-retrieving and using it.
-
-Intel ME firmware is in the flash chip. It is not needed when building coreboot.
-It can be extracted from the OEM firmware. You can also flash only the BIOS
-region to leave Intel ME firmware untouched.
-
-## Programming
-
-The laptop can be flashed internally under OEM firmware using [dell-flash-unlock].
-
-To flash with an external programmer, you need to remove the battery and the base cover.
-
-![Dell Latitude E7240 mainboard](e7240.webp)
-
-For more details have a look at the general [flashing tutorial].
-
-It is also possible to flash internally under coreboot.
-
-## Debugging
-
-The board can be debugged with EHCI debug. The EHCI debug port is next to the miniDP port.
-
-There's a serial port on dock, but it's not yet supported in coreboot.
-
-Schematic of this laptop can be found online. The board name is Compal LA-9431P.
-
-## Test status
-
-### Not working
-
-- EC ACPI
-- SD/MMC card reader (kernel reports "Timeout waiting for hardware cmd interrupt.")
-- No internal display before booting to OS when connected with a dock
-
-### Working
-
-- Integrated graphics init with libgfxinit
-- mSATA
-- WLAN
-- USB
-- Keyboard
-- Touchpad and the buttons on it
-- Dock: all USB ports, DisplayPort, eSATA
-- Internal flashing
-
-
-## Technology
-
-```{eval-rst}
-+------------------+-----------------------------+
-| CPU              | Intel Haswell-ULT           |
-+------------------+-----------------------------+
-| PCH              | Intel Lynx Point Low Power  |
-+------------------+-----------------------------+
-| EC               | SMSC MEC5075                |
-+------------------+-----------------------------+
-| Super I/O        | SMSC ECE5048                |
-+------------------+-----------------------------+
-| Coprocessor      | Intel Management Engine     |
-+------------------+-----------------------------+
-```
-
-[Dell Latitude E7240]: https://www.dell.com/support/home/en-us/product-support/product/latitude-e7240-ultrabook/docs
-[dell-flash-unlock]: https://github.com/nic3-14159/dell-flash-unlock
-[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md

Documentation/mainboard/dell/optiplex_9010.md

@@ -6,7 +6,7 @@ This page describes how to run coreboot on Dell OptiPlex 9010 SFF.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------+---------------------------------------------------------------+
 | CPU        | Intel Core 2nd Gen (Sandybridge) or 3rd Gen (Ivybridge)       |
 +------------+---------------------------------------------------------------+
@@ -28,7 +28,7 @@ More specifications on [Dell OptiPlex 9010 specifications].
 
 ## Required proprietary blobs
 
-```{eval-rst}
+```eval_rst
 +------------------+---------------------------------+---------------------+
 | Binary file      | Apply                           | Required / Optional |
 +==================+=================================+=====================+
@@ -50,7 +50,7 @@ signature `SMSCUBIM`. The easiest way to do this is to use [UEFITool] and
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+--------------------------+
 | Type                | Value                    |
 +=====================+==========================+

Documentation/mainboard/emulation/qemu-riscv.md

@@ -3,9 +3,6 @@
 ## Building coreboot and running it in QEMU
 
 - Configure coreboot and run `make` as usual
-
-Run QEMU
-```
-qemu-system-riscv64 -M virt -m 1G -nographic -bios build/coreboot.rom \
-                    -drive if=pflash,file=./build/coreboot.rom,format=raw
-```
+- Run `util/riscv/make-spike-elf.sh build/coreboot.rom build/coreboot.elf` to
+  convert coreboot to an ELF that QEMU can load
+- Run `qemu-system-riscv64 -M virt -m 1024M -nographic -kernel build/coreboot.elf`

Documentation/mainboard/emulation/qemu-sbsa.md

@@ -1,42 +0,0 @@
-# QEMU SBSA emulator
-This page describes how to build and run ```coreboot``` for QEMU's sbsa-ref machine.
-The qemu-sbsa ```coreboot``` image acts as BL-3.3 for Arm Trusted Firmware (```TF-A```) and
-mainly takes care of setting up SMBIOS and ACPI tables, hence, in order to boot,
-you also need to supply a ```TF-A``` image.
-
-## Building TF-A
-
-You can build ```TF-A``` from source by fetching
-```
-https://github.com/ARM-software/arm-trusted-firmware
-```
-and building the qemu-sbsa platform
-```
-PLAT=qemu_sbsa
-```
-Upon entry, ```coreboot``` expects a FDT pointer in x0, so make sure to compile ```TF-A``` with
-```
-ARM_LINUX_KERNEL_AS_BL33=1
-```
-This will force ```TF-A``` to pass a pointer to the FDT in x0.
-
-## Building coreboot
-
-Simply select the qemu-sbsa board and, optionally, configure a payload. We recommend
-the ```leanefi``` payload. ```leanefi``` will setup a minimal set of UEFI services, just enough
-to boot into a linux kernel.
-
-## Running coreboot in QEMU
-
-Once you have obtained ```TF-A``` and ```coreboot``` images, launch qemu via
-
-```bash
-qemu-system-aarch64 -nographic -m 1024 -M sbsa-ref -pflash <path/to/TFA.fd> \
-                                                   -pflash <path/to/coreboot.rom>
-```
-
-## LBBR bootflow
-
-arm and 9elements worked together in order to create a LBBR compliant bootflow
-consisting of ```TF-A```, ```coreboot```, ```leanefi``` and ```LinuxBoot```. A proof of concept
-can be found here https://gitlab.arm.com/systemready/firmware-build/linuxboot/lbbr-coreboot-poc

Documentation/mainboard/facebook/fbg1701.md

@@ -63,7 +63,7 @@ Specifically, it's a Winbond W25Q64FV (3.3V), whose datasheet can be found
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | SoC              | Intel Atom Processor N3710                       |
 +------------------+--------------------------------------------------+

Documentation/mainboard/facebook/monolith.md

@@ -14,7 +14,7 @@ Intel company provides [Firmware Support Package (2.0)](../../soc/intel/fsp/inde
 
 FSP Information:
 
-```{eval-rst}
+```eval_rst
 +-----------------------------+-------------------+-------------------+
 | FSP Project Name            | Directory         | Specification     |
 +-----------------------------+-------------------+-------------------+
@@ -116,7 +116,7 @@ output.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | SoC              | Intel Kaby Lake U                                |
 +------------------+--------------------------------------------------+

Documentation/mainboard/foxconn/d41s.md

@@ -14,7 +14,7 @@ The default options for this board should result in a fully working image:
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+--------+
 | Type                | Value  |
 +=====================+========+
@@ -56,7 +56,7 @@ To do this gently take the SPI flash out of its socket and flash with your progr
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+------------------+
 | Northbridge      | Intel Pinevew    |
 +------------------+------------------+

Documentation/mainboard/gigabyte/ga-g41m-es2l.md

@@ -6,7 +6,7 @@ This motherboard [also works with Libreboot](https://libreboot.org/docs/install/
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Type             | Value                                            |
 +==================+==================================================+
@@ -30,7 +30,7 @@ This motherboard [also works with Libreboot](https://libreboot.org/docs/install/
 
 ## Preparation
 
-```{eval-rst}
+```eval_rst
 For more datails how to get sources and build the toolchain, see :doc:`../../tutorial/part1`.
 ```
 
@@ -140,7 +140,7 @@ Built gigabyte/ga-g41m-es2l (GA-G41M-ES2L)
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 In addition to the information here, please see the
 :doc:`../../tutorial/flashing_firmware/index`.
 ```

Documentation/mainboard/gigabyte/ga-h61m-s2pv.md

@@ -5,7 +5,7 @@ from [Gigabyte].
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+
@@ -59,7 +59,7 @@ However, this makes DualBIOS unable to recover from a bad flash for some reason.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/hp/2170p.md

@@ -1,91 +0,0 @@
-# HP EliteBook 2170p
-
-This page is about the notebook [HP EliteBook 2170p].
-
-## Release status
-
-HP EliteBook 2170p was released in 2012 and is now end of life.
-It can be bought from a secondhand market like Taobao or eBay.
-
-## Required proprietary blobs
-
-The following blobs are required to operate the hardware:
-1. EC firmware
-2. Intel ME firmware
-
-EC firmware can be retrieved from the HP firmware update image, or the firmware
-backup of the laptop. EC Firmware is part of the coreboot build process.
-The guide on extracting EC firmware and using it to build coreboot is in
-document [HP Laptops with KBC1126 Embedded Controller](hp_kbc1126_laptops).
-
-Intel ME firmware is in the flash chip. It is not needed when building coreboot.
-
-## Programming
-
-The flash chip is located between the memory slots, WWAN card and CPU,
-covered by the base enclosure, which needs to be removed according to
-the [Maintenance and Service Guide] to access the flash chip. Unlike
-other variants, the flash chip on 2170p is socketed, so it can be taken
-off and operated with an external programmer.
-
-Pin 1 of the flash chip is at the side near the CPU.
-
-![Flash Chip in 2170p](2170p_flash.jpg)
-
-For more details have a look at the general [flashing tutorial].
-
-## Debugging
-
-The board can be debugged with serial port on the dock or EHCI debug.
-The EHCI debug port is the left USB3 port.
-
-## Test status
-
-### Known issues
-
-- GRUB payload freezes if at_keyboard module is in the GRUB image
-  ([bug #141])
-
-### Untested
-
-- Fingerprint Reader
-- Dock: Parallel port, PS/2 mouse, S-Video port
-
-### Working
-
-- Integrated graphics init with libgfxinit
-- SATA
-- Audio: speaker and microphone
-- Ethernet
-- WLAN
-- WWAN
-- Bluetooth
-- SD Card Reader
-- SmartCard Reader
-- USB
-- DisplayPort
-- Keyboard, touchpad and trackpoint
-- EC ACPI support and thermal control
-- Dock: all USB ports, DVI-D, Serial debug, PS/2 keyboard
-- TPM
-- Internal flashing when IFD is unlocked
-- Using `me_cleaner`
-
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| CPU              | Intel Sandy/Ivy Bridge (FCPGA988)                |
-+------------------+--------------------------------------------------+
-| PCH              | Intel Panther Point QM77                         |
-+------------------+--------------------------------------------------+
-| EC               | SMSC KBC1126                                     |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[HP EliteBook 2170p]: https://support.hp.com/us-en/product/hp-elitebook-2170p-notebook-pc/5245427
-[Maintenance and Service Guide]: http://h10032.www1.hp.com/ctg/Manual/c03387961.pdf
-[flashing tutorial]: ../../tutorial/flashing_firmware/ext_power.md

Documentation/mainboard/hp/2560p.md

@@ -80,7 +80,7 @@ Schematic of this laptop can be found on [Lab One].
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | CPU              | Intel Sandy/Ivy Bridge (FCPGA988)                |
 +------------------+--------------------------------------------------+

Documentation/mainboard/hp/8560w.md

@@ -1,80 +0,0 @@
-# HP EliteBook 8560w
-
-This page describes how to run coreboot on the [HP EliteBook 8560w].
-
-## Required proprietary blobs
-
-- Intel Firmware Descriptor, ME and GbE firmware
-- EC: please read [HP Laptops with KBC1126 Embedded Controller](hp_kbc1126_laptops)
-
-## Flashing instructions
-
-When running vendor firmware, external flashing is needed.
-
-HP EliteBook 8560w has an 8MiB SOIC-8 flash chip on the bottom of the
-mainboard. You just need to remove the service cover, and use an SOIC-8
-clip to read and flash the chip.
-
-![8560w_chip_location](8560w_flash.webp)
-
-```{eval-rst}
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | no         |
-+---------------------+------------+
-| Model               | MX25L6406E |
-+---------------------+------------+
-| Size                | 8 MiB      |
-+---------------------+------------+
-| Package             | SOIC-8     |
-+---------------------+------------+
-| Write protection    | no         |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| In circuit flashing | yes        |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-## Working
-
-- i7-2720QM, 8G+8G
-- Arch Linux boot from SeaBIOS payload
-- EHCI debug: the port is beside the eSATA port
-- SATA
-- eSATA
-- USB2 and USB3
-- keyboard
-- Gigabit Ethernet
-- WLAN
-- WWAN
-- VGA and DisplayPort
-- audio
-- EC ACPI
-- Using `me_cleaner`
-- dock: PS/2 keyboard, USB, DisplayPort
-- TPM
-- S3 suspend/resume
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| Super I/O        | SMSC LPC47n217                                   |
-+------------------+--------------------------------------------------+
-| EC               | SMSC KBC1126                                     |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[HP EliteBook 8560w]: https://support.hp.com/us-en/product/hp-elitebook-8560w-mobile-workstation/5071171

Documentation/mainboard/hp/8760w.md

@@ -7,7 +7,7 @@ checkout the [code on gerrit] to build coreboot for the laptop.
 
 ## Flashing coreboot
 
-```{eval-rst}
+```eval_rst
 +---------------------+------------+
 | Type                | Value      |
 +=====================+============+
@@ -66,7 +66,7 @@ clip to read and flash the chip.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+

Documentation/mainboard/hp/compaq_8200_sff.md

@@ -13,100 +13,31 @@ The following things are still missing from this coreboot port:
 
 ## Flashing coreboot
 
-```{eval-rst}
-+---------------------+-------------------------+
-| Type                | Value                   |
-+=====================+=========================+
-| Socketed flash      | no                      |
-+---------------------+-------------------------+
-| Model               | MX25L6406E/MX25L6408E   |
-+---------------------+-------------------------+
-| Size                | 8 MiB                   |
-+---------------------+-------------------------+
-| In circuit flashing | yes                     |
-+---------------------+-------------------------+
-| Package             | SOIC-8                  |
-+---------------------+-------------------------+
-| Write protection    | bios region             |
-+---------------------+-------------------------+
-| Dual BIOS feature   | No                      |
-+---------------------+-------------------------+
-| Internal flashing   | yes                     |
-+---------------------+-------------------------+
-```
-
-### Flash layout
-The original layout of the flash should look like this:
-```
-00000000:00000fff fd
-00510000:007fffff bios
-00003000:0050ffff me
-00001000:00002fff gbe
+```eval_rst
++---------------------+------------+
+| Type                | Value      |
++=====================+============+
+| Socketed flash      | no         |
++---------------------+------------+
+| Model               | MX25L6406E |
++---------------------+------------+
+| Size                | 8 MiB      |
++---------------------+------------+
+| In circuit flashing | yes        |
++---------------------+------------+
+| Package             | SOIC-8     |
++---------------------+------------+
+| Write protection    | No         |
++---------------------+------------+
+| Dual BIOS feature   | No         |
++---------------------+------------+
+| Internal flashing   | yes        |
++---------------------+------------+
 ```
 
 ### Internal programming
 
 The SPI flash can be accessed using [flashrom].
-```console
-$ flashrom -p internal -c MX25L6406E/MX25L6408E -w coreboot.rom
-```
-
-After shorting the FDO jumper you gain access to the full flash, but you
-still cannot write in the bios region due to SPI protected ranges.
-
-**Position of FDO jumper close to the IO and second fan connector**
-![][compaq_8200_jumper]
-
-[compaq_8200_jumper]: compaq_8200_sff_jumper.jpg
-
-To write to the bios region you can use an [IFD Hack] originally developed
-for MacBooks, but with modified values described in this guide.
-You should read both guides before attempting the procedure.
-
-Since you can still write in the flash descriptor, you can shrink
-the ME and then move the bios region into where the ME originally was.
-coreboot does not by default restrict writing to any part of the flash, so
-you will first flash a small coreboot build and after it boots, flash
-the full one.
-
-The temporary flash layout with the neutered ME firmware should look like this:
-```
-00000000:00000fff fd
-00023000:001fffff bios
-00003000:00022fff me
-00001000:00002fff gbe
-00200000:007fffff pd
-```
-
-It is very important to use these exact numbers or you will need to fix it
-using external flashing, but you should already be familiar with the risks
-if you got this far.
-
-The temporary ROM chip size to set in menuconfig is 2 MB but the default
-CBFS size is too large for that, you can use up to about 0x1D0000.
-
-When building both the temporary and the permanent installation, don't forget
-to also add the gigabit ethernet configuration when adding the flash descriptor
-and ME firmware.
-
-You can pad the ROM to the required 8MB with zeros using:
-```console
-$ dd if=/dev/zero of=6M.bin bs=1024 count=6144
-$ cat coreboot.rom 6M.bin > coreboot8.rom
-```
-
-If you want to continue using the neutered ME firmware use this flash layout
-for stage 2:
-```
-00000000:00000fff fd
-00023000:007fffff bios
-00003000:00022fff me
-00001000:00002fff gbe
-```
-
-If you want to use the original ME firmware use the original flash layout.
-
-More about flashing internally and getting the flash layout [here](../../tutorial/flashing_firmware/index.md).
 
 ### External programming
 
@@ -128,7 +59,7 @@ as otherwise there's not enough space near the flash.
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+--------------------------------------------------+
 | Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
 +------------------+--------------------------------------------------+
@@ -143,7 +74,7 @@ as otherwise there's not enough space near the flash.
 | Coprocessor      | Intel ME                                         |
 +------------------+--------------------------------------------------+
 ```
-[IFD Hack]: https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/changes/70/38770/4/Documentation/flash_tutorial/int_macbook.md/
+
 [Compaq 8200 Elite SFF]: https://support.hp.com/us-en/document/c03414707
 [HP]: https://www.hp.com/
 [flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/hp/compaq_8300_usdt.md

@@ -1,65 +0,0 @@
-# HP Compaq Elite 8300 USDT
-
-This page describes how to run coreboot on the [Compaq Elite 8300 USDT] desktop
-from [HP].
-
-## Flashing coreboot
-
-```{eval-rst}
-+---------------------+-------------+
-| Type                | Value       |
-+=====================+=============+
-| Socketed flash      | no          |
-+---------------------+-------------+
-| Model               | W25Q128BVFG |
-+---------------------+-------------+
-| Size                | 16 MiB      |
-+---------------------+-------------+
-| In circuit flashing | yes         |
-+---------------------+-------------+
-| Package             | SOIC-16     |
-+---------------------+-------------+
-| Write protection    | No          |
-+---------------------+-------------+
-| Dual BIOS feature   | No          |
-+---------------------+-------------+
-```
-
-### Internal programming
-
-Internal programming is possible. Shorting the Flash Descriptor Override
-(FDO) jumper bypasses all write protections.
-
-### External programming
-
-Remove the lid. The flash chip can be found on the edge opposite to the CPU.
-There is a spot for a "ROM RCVRY" header next to the flash chip but it is
-unpopulated. If you don't feel like using a clip, you can easily solder
-a standard pin header there yourself and use it for programming.
-
-Programming powers some parts of the board. Programming when
-Wake on LAN is active works great.
-
-## Technology
-
-```{eval-rst}
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| SuperIO          | NPCD379HAKFX                                     |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel ME                                         |
-+------------------+--------------------------------------------------+
-```
-
-### SuperIO
-
-This board has a Nuvoton NPCD379 SuperIO chip. Fan speed and PS/2 keyboard work
-fine using coreboot's existing code for :doc:`../../superio/nuvoton/npcd378`.
-
-[Compaq Elite 8300 USDT]: https://support.hp.com/gb-en/product/hp-compaq-elite-8300-ultra-slim-pc/5232866
-[HP]: https://www.hp.com/

Documentation/mainboard/hp/elitebook_820_g2.md

@@ -1,141 +0,0 @@
-# HP EliteBook 820 G2
-
-This page is about the notebook [HP EliteBook 820 G2].
-
-## Release status
-
-HP EliteBook 820 G2 was released in 2015 and is now end of life.
-It can be bought from a secondhand market like Taobao or eBay.
-
-## Required proprietary blobs
-
-The following blobs are required to operate the hardware:
-
-1. EC firmware
-2. Intel ME firmware
-3. Broadwell mrc.bin and refcode.elf
-
-HP EliteBook 820 G2 uses SMSC MEC1324 as its embedded controller.
-The EC firmware is stored in the flash chip, but we don't need to touch it
-or use it in the coreboot build process.
-
-Intel ME firmware is in the flash chip. It is not needed when building coreboot.
-
-The Broadwell memory reference code binary and reference code blob is needed
-when building coreboot. Read the document [Blobs used in Intel Broadwell boards]
-on how to get these blobs.
-
-## Programming
-
-Before flashing, remove the battery and the hard drive cover according to the
-[Maintenance and Service Guide] of this laptop.
-
-HP EliteBook 820 G2 has two flash chips, a 16MiB system flash, and a 2MiB
-private flash. To install coreboot, we need to program both flash chips.
-Read [HP Sure Start] for detailed information.
-
-![HP EliteBook 820 G2 flash chip](elitebook_820_g2_flash.jpg)
-
-To access the system flash, we need to connect the AC adapter to the machine,
-then clip on the flash chip with an SOIC-8 clip. An [STM32-based flash programmer]
-made with an STM32 development board is tested to work.
-
-To access the private flash chip, we can use a ch341a based flash programmer and
-flash the chip with the AC adapter disconnected.
-
-To flash coreboot on a board running OME firmware, create a backup for both flash
-chips, then do the following:
-
-1. Erase the private flash to disable the IFD protection
-2. Modify the IFD to shrink the BIOS region, so that we can put the firmware outside
-   the protected flash region
-
-To erase the private flash chip, attach it with the flash programmer via the SOIC-8 clip,
-then run:
-
-    flashrom -p <programmer> --erase
-
-To modify the IFD, write the following flash layout to a file:
-
-    00000000:00000fff fd
-    00001000:00002fff gbe
-    00003000:005fffff me
-    00600000:00bfffff bios
-    00eb5000:00ffffff pd
-
-Suppose the above layout file is ``layout.txt`` and the origin content of the system flash
-is in ``factory-sys.rom``, run:
-
-    ifdtool -n layout.txt factory-sys.rom
-
-Then a flash image with a new IFD will be in ``factory-sys.rom.new``.
-
-Flash the IFD of the system flash:
-
-    flashrom -p <programmer> --ifd -i fd -w factory-sys.rom.new
-
-Then flash the coreboot image:
-
-    # first extend the 12M coreboot.rom to 16M
-    fallocate -l 16M build/coreboot.rom
-    flashrom -p <programmer> --ifd -i bios -w build/coreboot.rom
-
-After coreboot is installed, the coreboot firmware can be updated with internal flashing:
-
-    flashrom -p internal --ifd -i bios --noverify-all -w build/coreboot.rom
-
-## Debugging
-
-The board can be debugged with EHCI debug. The EHCI debug port is the USB port on the left.
-
-## Test status
-
-### Untested
-
-- NFC module
-- Fingerprint reader
-- Smart Card reader
-
-### Working
-
-- mainboards with i3-5010U, i5-5300U CPU, 16G+8G DDR3L memory
-- SATA and M.2 SATA disk
-- PCIe SSD
-- Webcam
-- Touch screen
-- Audio output from speaker and headphone jack
-- Intel GbE (needs a modified refcode documented in [Blobs used in Intel Broadwell boards])
-- WLAN
-- WWAN
-- SD card reader
-- Internal LCD, DisplayPort and VGA video outputs
-- Dock
-- USB
-- Keyboard and touchpad
-- EC ACPI
-- S3 resume
-- TPM
-- Arch Linux with Linux 5.11.16
-- Broadwell MRC version 2.6.0 Build 0 and refcode from Purism Librem 13 v1
-- Graphics initialization with libgfxinit
-- Payload: SeaBIOS 1.16.2
-- EC firmware: KBC Revision 96.54 from OEM firmware version 01.05
-- Internal flashing under coreboot
-
-## Technology
-
-```{eval-rst}
-+------------------+-----------------------------+
-| SoC              | Intel Broadwell             |
-+------------------+-----------------------------+
-| EC               | SMSC MEC1324                |
-+------------------+-----------------------------+
-| Coprocessor      | Intel Management Engine     |
-+------------------+-----------------------------+
-```
-
-[HP EliteBook 820 G2]: https://support.hp.com/us-en/product/HP-EliteBook-820-G2-Notebook-PC/7343192/
-[Blobs used in Intel Broadwell boards]: ../../soc/intel/broadwell/blobs.md
-[Maintenance and Service Guide]: http://h10032.www1.hp.com/ctg/Manual/c04775894.pdf
-[STM32-based flash programmer]: https://github.com/dword1511/stm32-vserprog
-[HP Sure Start]: hp_sure_start.md

Documentation/mainboard/hp/folio_9480m.md

@@ -138,7 +138,7 @@ The board can be debugged with EHCI debug. The EHCI debug port is the USB port o
 
 ## Technology
 
-```{eval-rst}
+```eval_rst
 +------------------+-----------------------------+
 | CPU              | Intel Haswell-ULT           |
 +------------------+-----------------------------+