Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
6794ce02d4 | ||
|
5f0b80b880 |
@@ -17,9 +17,6 @@
|
||||
--ignore CONFIG_DESCRIPTION
|
||||
--ignore MISSING_SPACE
|
||||
--ignore CORRUPTED_PATCH
|
||||
--ignore SPDX_LICENSE_TAG
|
||||
--ignore UNDOCUMENTED_DT_STRING
|
||||
--ignore PRINTK_WITHOUT_KERN_LEVEL
|
||||
|
||||
# FILE_PATH_CHANGES seems to not be working correctly. It will
|
||||
# choke on added / deleted files even if the MAINTAINERS file
|
||||
|
||||
@@ -1,21 +1,10 @@
|
||||
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
|
||||
BasedOnStyle: LLVM
|
||||
Language: Cpp
|
||||
IndentWidth: 8
|
||||
UseTab: Always
|
||||
BreakBeforeBraces: Linux
|
||||
AllowShortIfStatementsOnASingleLine: false
|
||||
IndentCaseLabels: false
|
||||
SortIncludes: false
|
||||
ContinuationIndentWidth: 8
|
||||
ColumnLimit: 80
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
# EditorConfig: https://EditorConfig.org
|
||||
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = tab
|
||||
tab_width = 8
|
||||
charset = utf-8
|
||||
insert_final_newline = true
|
||||
end_of_line = lf
|
||||
trim_trailing_whitespace = true
|
||||
111
.gitignore
vendored
111
.gitignore
vendored
@@ -1,3 +1,6 @@
|
||||
payloads/libpayload/install/
|
||||
payloads/nvramcui/build
|
||||
payloads/nvramcui/libpayload
|
||||
junit.xml
|
||||
abuild*.xml
|
||||
.config
|
||||
@@ -8,25 +11,57 @@ defconfig
|
||||
.ccwrap
|
||||
build/
|
||||
coreboot-builds/
|
||||
coreboot-builds*/
|
||||
|
||||
payloads/coreinfo/lpbuild/
|
||||
payloads/coreinfo/lp.config*
|
||||
payloads/external/depthcharge/depthcharge/
|
||||
payloads/external/FILO/filo/
|
||||
payloads/external/GRUB2/grub2/
|
||||
payloads/external/SeaBIOS/seabios/
|
||||
payloads/external/tianocore/tianocore/
|
||||
payloads/external/tint/tint/
|
||||
payloads/external/U-Boot/u-boot/
|
||||
payloads/external/Memtest86Plus/memtest86plus/
|
||||
payloads/external/iPXE/ipxe/
|
||||
util/crossgcc/acpica-unix-*/
|
||||
util/crossgcc/binutils-*/
|
||||
util/crossgcc/build-*BINUTILS/
|
||||
util/crossgcc/build-*EXPAT/
|
||||
util/crossgcc/build-*GCC/
|
||||
util/crossgcc/build-*GDB/
|
||||
util/crossgcc/build-*GMP/
|
||||
util/crossgcc/build-*LIBELF/
|
||||
util/crossgcc/build-*MPC/
|
||||
util/crossgcc/build-*MPFR/
|
||||
util/crossgcc/build-*PYTHON/
|
||||
util/crossgcc/build-*LVM/
|
||||
util/crossgcc/build-*IASL/
|
||||
util/crossgcc/expat-*/
|
||||
util/crossgcc/gcc-*/
|
||||
util/crossgcc/gdb-*/
|
||||
util/crossgcc/gmp-*/
|
||||
util/crossgcc/libelf-*/
|
||||
util/crossgcc/mingwrt-*/
|
||||
util/crossgcc/mpc-*/
|
||||
util/crossgcc/mpfr-*/
|
||||
util/crossgcc/Python-*/
|
||||
util/crossgcc/*.src/
|
||||
util/crossgcc/tarballs/
|
||||
util/crossgcc/w32api-*/
|
||||
util/crossgcc/xgcc/
|
||||
util/crossgcc/xgcc-*/
|
||||
util/crossgcc/xgcc
|
||||
site-local
|
||||
|
||||
*.\#
|
||||
*.a
|
||||
*.bin
|
||||
*.debug
|
||||
!Kconfig.debug
|
||||
*.elf
|
||||
*.fd
|
||||
*.o
|
||||
*.o.d
|
||||
*.out
|
||||
*.pyc
|
||||
*.sw[po]
|
||||
/*.rom
|
||||
.test
|
||||
.dependencies
|
||||
coreboot-builds*/
|
||||
|
||||
# Development friendly files
|
||||
tags
|
||||
@@ -36,9 +71,67 @@ tags
|
||||
xgcc/
|
||||
tarballs/
|
||||
|
||||
# editor backup files, temporary files, IDE project files
|
||||
#
|
||||
# KDE editors create lots of backup files whenever
|
||||
# a file is edited, so just ignore them
|
||||
*~
|
||||
*.kate-swp
|
||||
# Ignore Kdevelop project file
|
||||
*.kdev4
|
||||
|
||||
util/*/.dependencies
|
||||
util/*/.test
|
||||
util/amdfwtool/amdfwtool
|
||||
util/archive/archive
|
||||
util/bimgtool/bimgtool
|
||||
util/bincfg/bincfg
|
||||
util/board_status/board-status
|
||||
util/cbfstool/cbfs-compression-tool
|
||||
util/cbfstool/cbfstool
|
||||
util/cbfstool/fmaptool
|
||||
util/cbfstool/ifwitool
|
||||
util/cbfstool/rmodtool
|
||||
util/cbmem/.dependencies
|
||||
util/cbmem/cbmem
|
||||
util/dumpmmcr/dumpmmcr
|
||||
util/ectool/ectool
|
||||
util/futility/futility
|
||||
util/genprof/genprof
|
||||
util/getpir/getpir
|
||||
util/ifdtool/ifdtool
|
||||
util/ifdfake/ifdfake
|
||||
util/intelmetool/intelmetool
|
||||
util/inteltool/.dependencies
|
||||
util/inteltool/inteltool
|
||||
util/intelvbttool/intelvbttool
|
||||
util/k8resdump/k8resdump
|
||||
util/lbtdump/lbtdump
|
||||
util/mptable/mptable
|
||||
util/msrtool/Makefile
|
||||
util/msrtool/Makefile.deps
|
||||
util/msrtool/msrtool
|
||||
util/nvramtool/.dependencies
|
||||
util/nvramtool/nvramtool
|
||||
util/optionlist/Options.wiki
|
||||
util/romcc/build
|
||||
util/runfw/googlesnow
|
||||
util/superiotool/superiotool
|
||||
util/vgabios/testbios
|
||||
util/viatool/viatool
|
||||
util/autoport/autoport
|
||||
util/kbc1126/kbc1126_ec_dump
|
||||
util/kbc1126/kbc1126_ec_insert
|
||||
|
||||
documentation/*.aux
|
||||
documentation/*.idx
|
||||
documentation/*.log
|
||||
documentation/*.toc
|
||||
documentation/*.out
|
||||
documentation/*.pdf
|
||||
documentation/cpukconfig.tex
|
||||
documentation/mainboardkconfig.tex
|
||||
documentation/skconfig.tex
|
||||
documentation/socketfkconfig.tex
|
||||
Documentation/_build
|
||||
|
||||
doxygen/*
|
||||
|
||||
37
.gitmodules
vendored
37
.gitmodules
vendored
@@ -21,40 +21,3 @@
|
||||
[submodule "libgfxinit"]
|
||||
path = 3rdparty/libgfxinit
|
||||
url = ../libgfxinit.git
|
||||
[submodule "3rdparty/fsp"]
|
||||
path = 3rdparty/fsp
|
||||
url = ../fsp.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "opensbi"]
|
||||
path = 3rdparty/opensbi
|
||||
url = ../opensbi.git
|
||||
[submodule "intel-microcode"]
|
||||
path = 3rdparty/intel-microcode
|
||||
url = ../intel-microcode.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "3rdparty/ffs"]
|
||||
path = 3rdparty/ffs
|
||||
url = ../ffs.git
|
||||
[submodule "3rdparty/amd_blobs"]
|
||||
path = 3rdparty/amd_blobs
|
||||
url = ../amd_blobs
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "3rdparty/cmocka"]
|
||||
path = 3rdparty/cmocka
|
||||
url = ../cmocka.git
|
||||
update = none
|
||||
[submodule "3rdparty/qc_blobs"]
|
||||
path = 3rdparty/qc_blobs
|
||||
url = ../qc_blobs.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "3rdparty/intel-sec-tools"]
|
||||
path = 3rdparty/intel-sec-tools
|
||||
url = ../9esec-security-tooling.git
|
||||
[submodule "3rdparty/stm"]
|
||||
path = 3rdparty/stm
|
||||
url = ../STM
|
||||
branch = stmpe
|
||||
|
||||
1
3rdparty/amd_blobs
vendored
1
3rdparty/amd_blobs
vendored
Submodule 3rdparty/amd_blobs deleted from 8c668ab552
2
3rdparty/arm-trusted-firmware
vendored
2
3rdparty/arm-trusted-firmware
vendored
Submodule 3rdparty/arm-trusted-firmware updated: a4c979ade4...693e278e30
2
3rdparty/blobs
vendored
2
3rdparty/blobs
vendored
Submodule 3rdparty/blobs updated: a59fb6e389...78a02a7f9d
2
3rdparty/chromeec
vendored
2
3rdparty/chromeec
vendored
Submodule 3rdparty/chromeec updated: a1afae4e00...927b64a0ba
1
3rdparty/cmocka
vendored
1
3rdparty/cmocka
vendored
Submodule 3rdparty/cmocka deleted from 672c5cee79
1
3rdparty/ffs
vendored
1
3rdparty/ffs
vendored
Submodule 3rdparty/ffs deleted from 3ec70fbc45
1
3rdparty/fsp
vendored
1
3rdparty/fsp
vendored
Submodule 3rdparty/fsp deleted from eb25f19ef7
1
3rdparty/intel-microcode
vendored
1
3rdparty/intel-microcode
vendored
Submodule 3rdparty/intel-microcode deleted from 0e4288f81f
1
3rdparty/intel-sec-tools
vendored
1
3rdparty/intel-sec-tools
vendored
Submodule 3rdparty/intel-sec-tools deleted from a86ff5d400
2
3rdparty/libgfxinit
vendored
2
3rdparty/libgfxinit
vendored
Submodule 3rdparty/libgfxinit updated: 3318bf2680...7628493a7e
2
3rdparty/libhwbase
vendored
2
3rdparty/libhwbase
vendored
Submodule 3rdparty/libhwbase updated: a3edc6ef32...66859712e4
1
3rdparty/opensbi
vendored
1
3rdparty/opensbi
vendored
Submodule 3rdparty/opensbi deleted from 215421ca61
1
3rdparty/qc_blobs
vendored
1
3rdparty/qc_blobs
vendored
Submodule 3rdparty/qc_blobs deleted from 6b7fe498eb
1
3rdparty/stm
vendored
1
3rdparty/stm
vendored
Submodule 3rdparty/stm deleted from 1f3258261a
2
3rdparty/vboot
vendored
2
3rdparty/vboot
vendored
Submodule 3rdparty/vboot updated: 4c523ed10f...392211f035
246
AUTHORS
246
AUTHORS
@@ -1,246 +0,0 @@
|
||||
# This is the list of coreboot authors for copyright purposes.
|
||||
#
|
||||
# This does not necessarily list everyone who has contributed code, since in
|
||||
# some cases, their employer may be the copyright holder. To see the full list
|
||||
# of contributors, and their email addresses, see the revision history in source
|
||||
# control.
|
||||
# Run the below commands in the coreboot repo for additional information.
|
||||
# To see a list of contributors: git log --pretty=format:%an | sort | uniq
|
||||
# For patches adding or removing a name: git log -i -S "NAME" --source --all
|
||||
|
||||
3mdeb Embedded Systems Consulting
|
||||
9elements Agency GmbH
|
||||
Abhinav Hardikar
|
||||
Advanced Computing Lab, LANL
|
||||
Advanced Micro Devices, Inc.
|
||||
AdaCore
|
||||
AG Electronics Ltd.
|
||||
Alex Thiessen
|
||||
Alex Züpke
|
||||
Alexander Couzens
|
||||
Alexandru Gagniuc
|
||||
Analog Devices Inc.
|
||||
Analogix Semiconductor
|
||||
Andre Heider
|
||||
Andriy Gapon
|
||||
Andy Fleming
|
||||
Angel Pons
|
||||
Anton Kochkov
|
||||
ARM Limited and Contributors
|
||||
Arthur Heymans
|
||||
Asami Doi
|
||||
ASPEED Technology Inc.
|
||||
Atheros Corporation
|
||||
Atmel Corporation
|
||||
BAP - Bruhnspace Advanced Projects
|
||||
Bill Xie
|
||||
Bitland Tech Inc.
|
||||
Boris Barbulovski
|
||||
Carl-Daniel Hailfinger
|
||||
Cavium Inc.
|
||||
Christoph Grenz
|
||||
Code Aurora Forum
|
||||
coresystems GmbH
|
||||
Corey Osgood
|
||||
Curt Brune
|
||||
Custom Ideas
|
||||
Damien Zammit
|
||||
Dave Airlie
|
||||
David Brownell
|
||||
David Greenman
|
||||
David Hendricks
|
||||
David Mosberger-Tang
|
||||
David Mueller
|
||||
David S. Peterson
|
||||
Denis 'GNUtoo' Carikli
|
||||
Denis Dowling
|
||||
DENX Software Engineering
|
||||
Derek Waldner
|
||||
Digital Design Corporation
|
||||
DMP Electronics Inc.
|
||||
Donghwa Lee
|
||||
Drew Eckhardt
|
||||
Dynon Avionics
|
||||
Edward O'Callaghan
|
||||
Egbert Eich
|
||||
ELSOFT AG
|
||||
Eltan B.V
|
||||
Elyes Haouas
|
||||
Eric Biederman
|
||||
Eswar Nallusamy
|
||||
Evgeny Zinoviev
|
||||
Fabian Kunkel
|
||||
Fabrice Bellard
|
||||
Facebook, Inc.
|
||||
Felix Held
|
||||
Felix Singer
|
||||
Frederic Potter
|
||||
Free Software Foundation, Inc.
|
||||
Freescale Semiconductor, Inc.
|
||||
Gary Jennejohn
|
||||
George Trudeau
|
||||
Gerald Van Baren
|
||||
Gerd Hoffmann
|
||||
Gergely Kiss
|
||||
Google LLC
|
||||
Greg Watson
|
||||
Guennadi Liakhovetski
|
||||
Hal Martin
|
||||
HardenedLinux
|
||||
Hewlett-Packard Development Company, L.P.
|
||||
Hewlett Packard Enterprise Development LP
|
||||
Huaqin Telecom Inc.
|
||||
IBM Corporation
|
||||
Idwer Vollering
|
||||
Igor Pavlov
|
||||
Imagination Technologies
|
||||
Infineon Technologies
|
||||
InKi Dae
|
||||
Intel Corporation
|
||||
Iru Cai
|
||||
Isaku Yamahata
|
||||
Ivan Vatlin
|
||||
James Ye
|
||||
Jason Zhao
|
||||
Joe Pillow
|
||||
Johanna Schander
|
||||
Jonas 'Sortie' Termansen
|
||||
Jonathan A. Kollasch
|
||||
Jonathan Neuschäfer
|
||||
Jordan Crouse
|
||||
Joseph Smith
|
||||
Keith Hui
|
||||
Keith Packard
|
||||
Kevin Cody-Little
|
||||
Kevin O'Connor
|
||||
Kontron Europe GmbH
|
||||
Kshitij
|
||||
Kyösti Mälkki
|
||||
Leah Rowe
|
||||
Lei Wen
|
||||
Li-Ta Lo
|
||||
Libra Li
|
||||
Libretrend LDA
|
||||
Linaro Limited
|
||||
Linus Torvalds
|
||||
Linux Networx, Inc.
|
||||
LiPPERT ADLINK Technology GmbH
|
||||
Lubomir Rintel
|
||||
Luc Verhaegen
|
||||
Maciej Matuszczyk
|
||||
Marc Bertens
|
||||
Marc Jones
|
||||
Marek Vasut
|
||||
Marius Gröger
|
||||
Martin Mares
|
||||
Martin Renters
|
||||
Martin Roth
|
||||
Marvell International Ltd.
|
||||
Marvell Semiconductor Inc.
|
||||
Matt DeVillier
|
||||
Maxim Polyakov
|
||||
MediaTek Inc.
|
||||
Michael Brunner
|
||||
Michael Schroeder
|
||||
Michael Niewöhner
|
||||
Mika Westerberg
|
||||
Mondrian Nuessle
|
||||
MontaVista Software, Inc.
|
||||
Myles Watson
|
||||
Network Appliance Inc.
|
||||
Nicholas Sielicki
|
||||
Nick Barker
|
||||
Nico Huber
|
||||
Nico Rikken
|
||||
Nicola Corna
|
||||
Nils Jacobs
|
||||
Nir Tzachar
|
||||
Nokia Corporation
|
||||
NVIDIA Corporation
|
||||
Olivier Langlois
|
||||
Ollie Lo
|
||||
Omar Pakker
|
||||
Online SAS
|
||||
Orion Technologies, LLC
|
||||
Patrick Georgi
|
||||
Patrick Rudolph
|
||||
Pattrick Hueper
|
||||
Paulo Alcantara
|
||||
Pavel Sayekat
|
||||
PC Engines GmbH
|
||||
Per Odlund
|
||||
Peter Korsgaard
|
||||
Peter Stuge
|
||||
Philipp Degler
|
||||
Philipp Deppenwiese
|
||||
Philipp Hug
|
||||
Protectli
|
||||
Purism SPC
|
||||
Qualcomm Technologies
|
||||
Raptor Engineering, LLC
|
||||
Red Hat, Inc
|
||||
Reinhard Meyer
|
||||
Renze Nicolai
|
||||
Richard Spiegel
|
||||
Richard Woodruff
|
||||
Rob Landley
|
||||
Robert Reeves
|
||||
Robinson P. Tryon
|
||||
Rockchip, Inc.
|
||||
Romain Lievin
|
||||
Roman Zippel
|
||||
Ronald G. Minnich
|
||||
Rudolf Marek
|
||||
Russell King
|
||||
Ruud Schramp
|
||||
Sage Electronic Engineering, LLC
|
||||
Sam Ravnborg
|
||||
Samsung Electronics
|
||||
Samuel Holland
|
||||
SciTech Software, Inc.
|
||||
Sebastian Grzywna
|
||||
secunet Security Networks AG
|
||||
Sencore Inc
|
||||
Sergej Ivanov
|
||||
Siemens AG
|
||||
SiFive, Inc
|
||||
Silicon Integrated System Corporation
|
||||
Silverback Ltd.
|
||||
Stefan Reinauer
|
||||
Stefan Tauner
|
||||
Steve Magnani
|
||||
Steve Shenton
|
||||
ST Microelectronics
|
||||
SUSE LINUX AG
|
||||
Sven Schnelle
|
||||
Syed Mohammed Khasim
|
||||
System76
|
||||
Texas Instruments
|
||||
The Android Open Source Project
|
||||
The ChromiumOS Authors
|
||||
The Linux Foundation
|
||||
The Regents of the University of California
|
||||
Thomas Winischhofer
|
||||
Timothy Pearson
|
||||
Tobias Diedrich
|
||||
Tristan Corrick
|
||||
Tungsten Graphics, Inc.
|
||||
Tyan Computer Corp.
|
||||
ucRobotics Inc.
|
||||
University of Heidelberg
|
||||
Uwe Hermann
|
||||
VIA Technologies, Inc
|
||||
Vikram Narayanan
|
||||
Vipin Kumar
|
||||
Vladimir Serbinenko
|
||||
Vlado Cibic
|
||||
Wang Qing Pei
|
||||
Ward Vandewege
|
||||
Wilbert Duijvenvoorde
|
||||
Win Enterprises
|
||||
Wiwynn Corp.
|
||||
Wolfgang Denk
|
||||
YADRO
|
||||
Yann Collet
|
||||
Yinghai Lu
|
||||
Zachary Yedidia
|
||||
7
Documentation/.gitignore
vendored
7
Documentation/.gitignore
vendored
@@ -1,7 +0,0 @@
|
||||
*.aux
|
||||
*.idx
|
||||
*.log
|
||||
*.toc
|
||||
*.out
|
||||
*.pdf
|
||||
_build
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
162
Documentation/Intel/Board/Galileo_checklist.html
Normal file
162
Documentation/Intel/Board/Galileo_checklist.html
Normal file
@@ -0,0 +1,162 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Galileo Implementation Status</title>
|
||||
</title>
|
||||
<body>
|
||||
<h1>Galileo Implementation Status<br>2016/07/08 06:51:34 PDT</h1>
|
||||
<table>
|
||||
<tr><td colspan=2><b>Legend</b></td></tr>
|
||||
<tr><td bgcolor="#ffc0c0">Red</td><td>Required - To-be-implemented</td></tr>
|
||||
<tr><td bgcolor="#ffffc0">Yellow</td><td>Optional</td></tr>
|
||||
<tr><td bgcolor="#c0ffc0">Green</td><td>Implemented</td></tr>
|
||||
</table>
|
||||
<table>
|
||||
<tr valign="top">
|
||||
<td>
|
||||
<table border=1>
|
||||
<tr><th colspan=2>bootblock: 100% Done</th></tr>
|
||||
<tr><th>Type</th><th>Routine</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_c_entry</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_main_with_timestamp</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_mainboard_early_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_mainboard_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_pre_c_entry</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_protected_mode_entry</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_soc_early_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_soc_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>uart_init</td></tr>
|
||||
</table>
|
||||
</td>
|
||||
<td width=5> </td>
|
||||
<td>
|
||||
<table border=1>
|
||||
<tr><th colspan=2>romstage: 67% Done</th></tr>
|
||||
<tr><th>Type</th><th>Routine</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>arch_segment_loaded</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>backup_top_of_ram</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>boot_device_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>car_mainboard_post_console_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>car_mainboard_pre_console_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>car_soc_post_console_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>car_soc_pre_console_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>car_stage_entry</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>cbfs_master_header_locator</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>cbmem_fail_resume</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>clear_recovery_mode_switch</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>cpu_smi_handler</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>fill_power_state</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>get_sw_write_protect_state</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>get_top_of_ram</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>gpio_acpi_path</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>init_timer</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_add_dimm_info</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_check_ec_image</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>mainboard_fill_spd_data</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_io_trap_handler</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>mainboard_memory_init_params</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_post</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>mainboard_romstage_entry</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_save_dimm_info</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_apmc</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_gpi</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_sleep</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>map_oprom_vendev</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>migrate_power_state</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>mrc_cache_get_current_with_version</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>mrc_cache_stash_data_with_version</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>platform_prog_run</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>platform_segment_loaded</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>print_fsp_info</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>raminit</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>ramstage_cache_invalid</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>report_memory_config</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>romstage_common</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>save_chromeos_gpios</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>set_max_freq</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>setup_stack_and_mtrrs</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>smm_region</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>smm_region_size</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_after_ram_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_memory_init_params</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_mtrrs</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_get_variable_mtrr_count</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_memory_init_params</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>soc_pre_ram_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>southbridge_smi_handler</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_add</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_load_stage</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>timestamp_get</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_extend</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_finalize</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vboot_platform_prepare_reboot</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>verstage_mainboard_init</td></tr>
|
||||
</table>
|
||||
</td>
|
||||
<td width=5> </td>
|
||||
<td>
|
||||
<table border=1>
|
||||
<tr><th colspan=2>ramstage: 60% Done</th></tr>
|
||||
<tr><th>Type</th><th>Routine</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>acpi_create_serialio_ssdt</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>arch_segment_loaded</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>backup_top_of_ram</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>boot_device_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>cbfs_master_header_locator</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>cbmem_fail_resume</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>clear_recovery_mode_switch</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>cpu_smi_handler</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>fw_cfg_acpi_tables</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>get_sw_write_protect_state</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>get_top_of_ram</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>gpio_acpi_path</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>init_timer</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>lb_board</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>lb_framebuffer</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_add_dimm_info</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_io_trap_handler</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_post</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_silicon_init_params</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_apmc</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_gpi</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_sleep</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_suspend_resume</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>map_oprom_vendev</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>mirror_payload</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>northbridge_smi_handler</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>nvm_mmio_to_flash_offset</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>platform_prog_run</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>platform_segment_loaded</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>save_chromeos_gpios</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_bios_version</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_manufacturer</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_product_name</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_serial_number</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_set_uuid</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>smbios_mainboard_version</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>smm_disable_busmaster</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>soc_after_silicon_init</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_silicon_init_params</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>soc_fill_acpi_wake</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>soc_silicon_init_params</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>soc_skip_ucode_update</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>southbridge_smi_handler</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_add</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_load_stage</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>timestamp_get</td></tr>
|
||||
<tr bgcolor=#ffc0c0><td>Required</td><td>timestamp_tick_freq_mhz</td></tr>
|
||||
<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_extend</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_finalize</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_init</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>wifi_regulatory_domain</td></tr>
|
||||
<tr bgcolor=#ffffc0><td>Optional</td><td>write_smp_table</td></tr>
|
||||
</table>
|
||||
</td>
|
||||
<td width=5> </td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
@@ -222,7 +222,7 @@
|
||||
<li>Add the acpi_create_fadt routine
|
||||
<ol type="I">
|
||||
<li>fill in the ACPI header</li>
|
||||
<li>Call the acpi_fill_fadt routine</li>
|
||||
<li>Call the acpi_fill_in_fadt routine</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
<li><a target="_blank" href="../SoC/soc.html">SoC</a> support</li>
|
||||
<li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
|
||||
<li><a target="_blank" href="board.html">Board</a> support</li>
|
||||
<li><a target="_blank" href="Galileo_checklist.html">Implementation Checklist</a></li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
74
Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md
Normal file
74
Documentation/Intel/MultiProcessorInit/MultiProcessorInit.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Intel Common Code Block Publishing EFI_MP_SERVICES_PPI
|
||||
|
||||
## Introduction
|
||||
|
||||
This documentation is intended to document the purpose for creating EFI service
|
||||
Interface inside coreboot space to perform CPU feature programming on Application
|
||||
Processors for Intel 9th Gen (Cannon Lake) and beyond CPUs.
|
||||
|
||||
Today coreboot is capable enough to handle multi-processor initialization on IA platforms.
|
||||
|
||||
The multi-processor initialization code has to take care of lots of duties:
|
||||
|
||||
1 Bringing all cores out of reset
|
||||
2 Load latest microcode on all cores
|
||||
3 Sync latest MTRR snapshot between BSP and APs
|
||||
4 Perform sets of CPU feature programming
|
||||
* CPU Power & Thermal Management
|
||||
* Overclocking
|
||||
* Intel Trusted Execution Technology
|
||||
* Intel Software Guard Extensions
|
||||
* Intel Processor Trace etc.
|
||||
|
||||
This above CPU feature programming lists are expected to grow with current and future
|
||||
CPU complexity and there might be some cases where certain feature programming mightbe
|
||||
closed source in nature.
|
||||
|
||||
Platform code might need to compromise on those closed source nature of CPU programming
|
||||
if we don't plan to provide an alternate interface which can be used by coreboot to
|
||||
get-rid of such close source CPU programming.
|
||||
|
||||
## Proposal
|
||||
|
||||
As coreboot is doing CPU multi-processor initialization for IA platform before FSP-S
|
||||
initialization and having all possible information about cores in terms of maximum number
|
||||
of cores, APIC ids, stack size etc. It’s also possible for coreboot to extend its own
|
||||
support model and create a sets of APIs which later can be used by FSP to run CPU feature
|
||||
programming using coreboot published APIs.
|
||||
|
||||
Due to the fact that FSP is using EFI infrastructure and need to relying on install/locate
|
||||
PPI to perform certain API call, hence coreboot has to created MP services APIs known as
|
||||
EFI_MP_SERVICES_PPI as per PI specification volume 1, section 8.3.9.
|
||||
More details here: http://www.uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf
|
||||
|
||||
### coreboot to publish EFI_MP_SERVICES_PPI APIs
|
||||
| API | Description |
|
||||
|------------------------------|------------------------------------------------------------------|
|
||||
| PeiGetNumberOfProcessors | Get the number of CPU's. |
|
||||
| PeiGetProcessorInfo | Get information on a specific CPU. |
|
||||
| PeiStartupAllAPs | Activate all of the application processors. |
|
||||
| PeiStartupThisAP | Activate a specific application processor. |
|
||||
| PeiSwitchBSP | Switch the boot strap processor. |
|
||||
| PeiEnableDisableAP | Enable or disable an application processor. |
|
||||
| PeiWhoAmI | Identify the currently executing processor. |
|
||||
|------------------------------|------------------------------------------------------------------|
|
||||
|
||||
|
||||
## Code Flow
|
||||
|
||||
Here is proposed design flow with coreboot has implemented EFI_MP_SERVICES_PPI API and FSP will make
|
||||
use of the same to perform some CPU feature programming.
|
||||
|
||||
** coreboot-FSP MP init flow **
|
||||
![alt text][coreboot_publish_mp_service_api]
|
||||
|
||||
[coreboot_publish_mp_service_api]: coreboot_publish_mp_service_api.png "coreboot-fsp mp init flow"
|
||||
|
||||
## Benefits
|
||||
1. coreboot was using SkipMpInit=1 which will skip entire FSP CPU feature programming.
|
||||
With proposed model, coreboot will make use of SkipMpInit=0 which will allow to run all
|
||||
Silicon recommended CPU programming.
|
||||
2. CPU feature programming inside FSP will be more transparent than before as it’s using
|
||||
coreboot interfaces to execute those programming.
|
||||
3. coreboot will have more control over running those feature programming as API optimization
|
||||
handled by coreboot.
|
||||
|
Before Width: | Height: | Size: 120 KiB After Width: | Height: | Size: 120 KiB |
2174
Documentation/Intel/NativeRaminit/SandyBridge_registers.md
Normal file
2174
Documentation/Intel/NativeRaminit/SandyBridge_registers.md
Normal file
File diff suppressed because it is too large
Load Diff
135
Documentation/Intel/NativeRaminit/Sandybridge.md
Normal file
135
Documentation/Intel/NativeRaminit/Sandybridge.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Sandy Bridge Raminit
|
||||
|
||||
## Introduction
|
||||
|
||||
This documentation is intended to document the closed source memory controller
|
||||
hardware for Intel 2nd Gen (Sandy Bride) and 3rd Gen (Ivy Bridge) core-i CPUs.
|
||||
|
||||
The memory initialization code has to take care of lots of duties:
|
||||
1. Selection of operating frequency
|
||||
* Selection of common timings
|
||||
* Applying frequency specific compensation values
|
||||
* Read training of all populated channels
|
||||
* Write training of all populated channels
|
||||
* Adjusting delay networks of address and command signals
|
||||
* DQS training of all populated channels
|
||||
* Programming memory map
|
||||
* Report DRAM configuration
|
||||
* Error handling
|
||||
|
||||
## Definitions
|
||||
```eval_rst
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| Symbol | Description | Units | Valid region |
|
||||
+=========+===================================================================+============+==============+
|
||||
| SCK | DRAM system clock cycle time | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| tCK | DRAM system clock cycle time | 1/256th ns | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| DCK | Data clock cycle time: The time between two SCK clock edges | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| REFCK | Reference clock, either 100 or 133 | Mhz | 100, 133 |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| MULT | DRAM PLL multiplier | | [3-12] |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| XMP | Extreme Memory Profiles | | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
```
|
||||
|
||||
## (Inoffical) register documentation
|
||||
- [Sandy Bride - Register documentation](SandyBridge_registers.md)
|
||||
|
||||
## Frequency selection
|
||||
- [Sandy Bride - Frequency selection](Sandybridge_freq.md)
|
||||
|
||||
## Read training
|
||||
- [Sandy Bride - Read training](Sandybridge_read.md)
|
||||
|
||||
### SMBIOS type 17
|
||||
The SMBIOS specification allows to report the memory configuration in use.
|
||||
On GNU/Linux you can run `# dmidecode -t 17` to view it.
|
||||
Example output of dmidecode:
|
||||
|
||||
```
|
||||
Handle 0x0045, DMI type 17, 34 bytes
|
||||
Memory Device
|
||||
Array Handle: 0x0042
|
||||
Error Information Handle: Not Provided
|
||||
Total Width: 64 bits
|
||||
Data Width: 64 bits
|
||||
Size: 8192 MB
|
||||
Form Factor: DIMM
|
||||
Set: None
|
||||
Locator: ChannelB-DIMM0
|
||||
Bank Locator: BANK 2
|
||||
Type: DDR3
|
||||
Type Detail: Synchronous
|
||||
Speed: 933 MHz
|
||||
Manufacturer: 0420
|
||||
Serial Number: 00000000
|
||||
Asset Tag: 9876543210
|
||||
Part Number: F3-1866C9-8GSR
|
||||
Rank: 2
|
||||
Configured Clock Speed: 933 MHz
|
||||
```
|
||||
The memory frequency printed by dmidecode is the active memory frequency. It's
|
||||
**not** the double datarate and it's **not** the one encoded maximum frequency
|
||||
in each DIMM's SPD.
|
||||
|
||||
> **Note:** This feature is available since coreboot 4.4
|
||||
|
||||
### MRC cache
|
||||
The name *MRC cache* might be missleading as in case of *Native ram init*
|
||||
there's no MRC, but for historical reasons it's still named *MRC cache*.
|
||||
The MRC cache is part of flash memory that is writeable by coreboot.
|
||||
At the end of the boot process coreboot will write the RAM training results to
|
||||
flash for future use, as RAM training is time intensive. Storing the results
|
||||
allows to boot faster on normal boot and allows to support S3 resume,
|
||||
as the RAM training results can't be stored in RAM (you need to configure
|
||||
the memory controller first to access RAM).
|
||||
|
||||
The MRC cache needs to be invalidated in case the memory configuration has
|
||||
been changed. To detect a changed memory configuration the CRC16 of each DIMM
|
||||
is stored to MRC cache.
|
||||
> **Note:** This feature is available since coreboot 4.4
|
||||
|
||||
### Error handling
|
||||
As of writing the only supported error handling is to disable the failing
|
||||
channel and restart the memory training sequence. It's very likely to succeed,
|
||||
as memory channels operate independent of each other.
|
||||
In case no DIMM could be initilized coreboot will halt. The screen will stay
|
||||
black until you power of your device. On some platforms there's additional
|
||||
feedback to indicate such an event.
|
||||
|
||||
If you find `dmidecode -t 17` to report only half of the memory installed,
|
||||
it's likely that a fatal memory init failure had happened.
|
||||
It is assumed, that a working board with less physical memory, is much better,
|
||||
than a board that doesn't boot at all.
|
||||
|
||||
> **Note:** This feature is available since coreboot 4.5
|
||||
|
||||
Try to swap memory modules and or try to use a different vendor. If nothing
|
||||
helps you could have a look at capter [Debuggin] or report a ticket
|
||||
at [ticket.coreboot.org]. Please provide a full RAM init log,
|
||||
that has been captured using EHCI debug.
|
||||
|
||||
To enable extensive RAM training logging enable the Kconfig option
|
||||
`DEBUG_RAM_SETUP`
|
||||
#### Lenovo Thinkpads
|
||||
Lenovo Thinkpads do have an additional feature to indicate that RAM init has
|
||||
failed and coreboot has died (it calls die() on fatal error, thus the name).
|
||||
The Kconfig options
|
||||
`H8_BEEP_ON_DEATH`
|
||||
`H8_FLASH_LEDS_ON_DEATH`
|
||||
enable blinking LEDs and enable a beep to indicate death.
|
||||
|
||||
> **Note:** This feature is available since coreboot 4.7
|
||||
|
||||
## Debugging
|
||||
It's recommended to use an external debugger, such as serial or EHCI debug
|
||||
dongle. In case of failing memory init the board might not boot at all,
|
||||
preventing you from using CBMEM.
|
||||
165
Documentation/Intel/NativeRaminit/Sandybridge_freq.md
Normal file
165
Documentation/Intel/NativeRaminit/Sandybridge_freq.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Frequency selection
|
||||
|
||||
## Introduction
|
||||
This chapter explains the frequency selection done on Sandybride and Ivybridge.
|
||||
|
||||
## Definitions
|
||||
```eval_rst
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| Symbol | Description | Units | Valid region |
|
||||
+=========+===================================================================+============+==============+
|
||||
| SCK | DRAM system clock cycle time | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| tCK | DRAM system clock cycle time | 1/256th ns | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| DCK | Data clock cycle time: The time between two SCK clock edges | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| MULT | DRAM PLL multiplier | | [3-12] |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| XMP | Extreme Memory Profiles | | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
```
|
||||
## SPD
|
||||
The [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect")
|
||||
located on every DIMM is factory program with various timings. One of them
|
||||
specifies the maximum clock frequency the DIMM should be used with. The
|
||||
operating frequency is stores as fixed point value (tCK), rounded to the next
|
||||
smallest supported operating frequency. Some
|
||||
[SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect")
|
||||
contains additional and optional
|
||||
[XMP](https://de.wikipedia.org/wiki/Extreme_Memory_Profile "Extreme Memory Profile")
|
||||
data, that stores so called "performance" modes, that advertises higher clock
|
||||
frequencies.
|
||||
|
||||
## XMP profiles
|
||||
At time of writing coreboot's raminit is able to parse XMP profile 1 and 2.
|
||||
Only **XMP profile 1** is being used in case it advertises:
|
||||
* 1.5V operating voltage
|
||||
* The channel's installed DIMM count doesn't exceed the XMP coded limit
|
||||
|
||||
In case the XMP profile doesn't fullfill those limits, the regular SPD will be
|
||||
used.
|
||||
> **Note:** XMP Profiles are supported since coreboot 4.4.
|
||||
|
||||
It is possible to ignore the max DIMM count limit set by XMP profiles.
|
||||
By activating Kconfig option `NATIVE_RAMINIT_IGNORE_XMP_MAX_DIMMS` it is
|
||||
possible to install two DIMMs per channel, even if XMP tells you not to do.
|
||||
|
||||
> **Note:** Ignoring XMP Profiles limit is supported since coreboot 4.7.
|
||||
|
||||
## Soft fuses
|
||||
Every board manufacturer does program "soft" fuses to indicate the maximum
|
||||
DRAM frequency supported. However, those fuses don't set a limit in hardware
|
||||
and thus are called "soft" fuses, as it is possible to ignore them.
|
||||
|
||||
> **Note:** Ignoring the fuses might cause system instability !
|
||||
|
||||
On Sandy Bride *CAPID0_A* is being read, and on Ivybridge *CAPID0_B* is being
|
||||
read. coreboot reads those registers and honors the limit in case the Kconfig
|
||||
option `CONFIG_NATIVE_RAMINIT_IGNORE_MAX_MEM_FUSES` wasn't set.
|
||||
Power users that want to let their RAM run at DRAM's "stock" frequency need to
|
||||
enable the Kconfig symbol.
|
||||
|
||||
It is possible to override the soft fuses limit by using a board-specific
|
||||
[devicetree](#devicetree) setting.
|
||||
|
||||
> **Note:** Ignoring max mem freq. fuses is supported since coreboot 4.7.
|
||||
|
||||
## <a name="hard_fuses"></a> Hard fuses
|
||||
"Hard" fuses are programmed by Intel and limit the maximum frequency that can
|
||||
be used on a given CPU/board/chipset. At time of writing there's no register
|
||||
to read this limit, before trying to set a given DRAM frequency. The memory PLL
|
||||
won't lock, indicating that the chosen memory multiplier isn't available. In
|
||||
this case coreboot tries the next smaller memory multiplier until the PLL will
|
||||
lock.
|
||||
|
||||
## <a name="devicetree"></a> Devicetree
|
||||
The devicetree register ```max_mem_clock_mhz``` overrides the "soft" fuses set
|
||||
by the board manufacturer.
|
||||
|
||||
By using this register it's possible to force a minimum operating frequency.
|
||||
|
||||
## Reference clock
|
||||
While Sandybride supports 133 MHz reference clock (REFCK), Ivy Bridge also
|
||||
supports 100 MHz reference clock. The reference clock is multiplied by the DRAM
|
||||
multiplier to select the DRAM frequency (SCK) by the following formula:
|
||||
|
||||
REFCK * MULT = 1 / DCK
|
||||
|
||||
> **Note:** Since coreboot 4.6 Ivy Bridge supports 100MHz REFCK.
|
||||
|
||||
## Sandy Bride's supported frequencies
|
||||
```eval_rst
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment |
|
||||
+============+===========+==================+=========================+===============+
|
||||
| 400 | DDR3-800 | 3 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 533 | DDR3-1066 | 4 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 666 | DDR3-1333 | 5 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 800 | DDR3-1600 | 6 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 933 | DDR3-1866 | 7 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 1066 | DDR3-2166 | 8 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
```
|
||||
|
||||
## Ivybridge's supported frequencies
|
||||
```eval_rst
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| SCK [Mhz] | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment |
|
||||
+============+===========+==================+=========================+===============+
|
||||
| 400 | DDR3-800 | 3 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 533 | DDR3-1066 | 4 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 666 | DDR3-1333 | 5 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 800 | DDR3-1600 | 6 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 933 | DDR3-1866 | 7 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 1066 | DDR3-2166 | 8 | 133 MHz | |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 700 | DDR3-1400 | 7 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 800 | DDR3-1600 | 8 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 900 | DDR3-1800 | 9 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 1000 | DDR3-2000 | 10 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 1100 | DDR3-2200 | 11 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
| 1200 | DDR3-2400 | 12 | 100 MHz | '1 |
|
||||
+------------+-----------+------------------+-------------------------+---------------+
|
||||
```
|
||||
> '1: since coreboot 4.6
|
||||
|
||||
## Multiplier selection
|
||||
coreboot select the maximum frequency to operate at by the following formula:
|
||||
```
|
||||
if devicetree's max_mem_clock_mhz > 0:
|
||||
freq_max := max_mem_clock_mhz
|
||||
else:
|
||||
freq_max := soft_fuse_max_mhz
|
||||
|
||||
for i in SPDs:
|
||||
freq_max := MIN(freq_max, ddr_spd_max_mhz[i])
|
||||
```
|
||||
|
||||
As you can see, by using DIMMs with different maximum DRAM frequencies, the
|
||||
slowest DIMMs' frequency will be selected, to prevent over-clocking it.
|
||||
|
||||
The selected frequency gives the PLL multiplier to operate at. In case the PLL
|
||||
locks (see Take me to [Hard fuses](#hard_fuses)) the frequency will be used for
|
||||
all DIMMs. At this point it's not possible to change the multiplier again,
|
||||
until the system has been powered off. In case the PLL doesn't lock, the next
|
||||
smaller multiplier will be used until a working multiplier will be found.
|
||||
153
Documentation/Intel/NativeRaminit/Sandybridge_read.md
Normal file
153
Documentation/Intel/NativeRaminit/Sandybridge_read.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Read training
|
||||
|
||||
## Introduction
|
||||
|
||||
This chapter explains the read training sequence done on Sandy Bride and
|
||||
Ivy Bridge memory initialization.
|
||||
|
||||
Read training is done to compensate the skew between DQS and SCK and to find
|
||||
the smallest supported roundtrip delay.
|
||||
|
||||
Every board does have a vendor depended routing topology, and can be equip
|
||||
with any combination of DDR3 memory modules, that introduces different
|
||||
skew between the memory lanes. With DDR3 a "Fly-By" routing topology
|
||||
has been introduced, that makes the biggest part of DQS-SCK skew.
|
||||
The memory code measures the actual skew and actives delay gates,
|
||||
that will "compensate" the skew.
|
||||
|
||||
When in read training the DRAM and the controller are placed in a special mode.
|
||||
On every read instruction the DRAM outputs a predefined pattern and the memory
|
||||
controller samples the DQS after a given delay. As the pattern is known, the
|
||||
actual delay of every lane can be measured.
|
||||
|
||||
The values programmed in read training effect DRAM-to-MC transfers only !
|
||||
|
||||
## Definitions
|
||||
```eval_rst
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| Symbol | Description | Units | Valid region |
|
||||
+=========+===================================================================+============+==============+
|
||||
| SCK | DRAM system clock cycle time | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| tCK | DRAM system clock cycle time | 1/256th ns | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| DCK | Data clock cycle time: The time between two SCK clock edges | s | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| timA | IO phase: The phase delay of the IO signals | 1/64th DCK | [0-512) |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| SPD | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| REFCK | Reference clock, either 100 or 133 | MHz | 100, 133 |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| MULT | DRAM PLL multiplier | | [3-12] |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| XMP | Extreme Memory Profiles | | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
| DQS | Data Strobe signal used to sample all lane's DQ signals | | |
|
||||
+---------+-------------------------------------------------------------------+------------+--------------+
|
||||
```
|
||||
## Hardware
|
||||
The hardware does have delay logic blocks that can delay the DQ / DQS of a
|
||||
lane/rank by one or multiple clock cylces and it does have delay logic blocks
|
||||
that can delay the signal by a multiple of 1/64th DCK per lane.
|
||||
|
||||
All delay values can be controlled via software by writing registers in the
|
||||
MCHBAR.
|
||||
|
||||
## IO phase
|
||||
|
||||
The IO phase can be adjusted in [0-512) * 1/64th DCK. Incrementing it by 64 is
|
||||
the same as Incrementing IO delay by 1.
|
||||
|
||||
## IO delay
|
||||
Delays the DQ / DQS signal by one or multiple clock cycles.
|
||||
|
||||
### Roundtrip time
|
||||
The roundtrip time is the time the memory controller waits for data arraving
|
||||
after a read has been issued. Due to clock-domain crossings, multiple
|
||||
delay instances and phase interpolators, the signal runtime to DRAM and back
|
||||
to memory controller defaults to 55 DCKs. The real roundtrip time has to be
|
||||
measured.
|
||||
|
||||
After a read command has been issued, a counter counts down until zero has been
|
||||
reached and activates the input buffers.
|
||||
|
||||
The following pictures shows the relationship between those three values.
|
||||
The picture was generated from 16 IO delay values times 64 timA values.
|
||||
The highest IO delay was set on the right-hand side, while the last block
|
||||
on the left-hand side has zero IO delay.
|
||||
|
||||
#### roundtrip 55 DCKs
|
||||
![alt text][timA_lane0-3_rt55]
|
||||
|
||||
[timA_lane0-3_rt55]: timA_lane0-3_rt55.png "timA for lane0 - lane3, roundtrip 55"
|
||||
|
||||
#### roundtrip 54 DCKs
|
||||
![alt text][timA_lane0-3_rt54]
|
||||
|
||||
[timA_lane0-3_rt54]: timA_lane0-3_rt54.png "timA for lane0 - lane3, roundtrip 54"
|
||||
|
||||
|
||||
#### roundtrip 53 DCKs
|
||||
![alt text][timA_lane0-3_rt53]
|
||||
|
||||
[timA_lane0-3_rt53]: timA_lane0-3_rt53.png "timA for lane0 - lane3, roundtrip 53"
|
||||
|
||||
As you can see the signal has some jitter as every sample was taken in a
|
||||
different loop iteration. The result register only contains a single bit per
|
||||
lane.
|
||||
|
||||
## Algorithm
|
||||
### Steps
|
||||
The algorithm finds the roundtrip time, IO delay and IO phase. The IO phase
|
||||
will be adjusted to match the falling edge of the preamble of each lane.
|
||||
The roundtrip time is adjusted to an minimal value, that still includes the
|
||||
preamble.
|
||||
|
||||
### Synchronize to data phase
|
||||
|
||||
The first measurement done in read-leveling samples all DQS values for one
|
||||
phase [0-64) * 1/64th DCK. It then searches for the middle of the low data
|
||||
symbol and adjusts timA to the found phase and thus the following measurements
|
||||
will be aligned to the low data symbol.
|
||||
The code assumes that the initial roundtrip time causes the measurement to be
|
||||
in the alternating pattern data phase.
|
||||
|
||||
### Finding the preamble
|
||||
After adjusting the IO phase to the middle of one data symbol the preamble will
|
||||
be located. Unlike the data phase, which is an alternating pattern (010101...),
|
||||
the preamble consists of two high data cycles.
|
||||
|
||||
The code decrements the IO delay/RTT and samples the DQS signal with timA
|
||||
untouched. As it has been positioned in the middle of the data symbol, it'll
|
||||
read as either "low" or "high".
|
||||
|
||||
If it's "low" we are still in the data phase.
|
||||
If it's "high" we have found the preamble.
|
||||
|
||||
The roundtrip time and IO delay will be adjusted until all lanes are aligned.
|
||||
The resulting IO delay is visible in the picture below.
|
||||
|
||||
** roundtrip time: 49 DCKs, IO delay (at blue point): 6 DCKs **
|
||||
![alt text][timA_lane0-3_discover_420x]
|
||||
|
||||
[timA_lane0-3_discover_420x]: timA_lane0-3_discover_420x.png "timA for lane0 - lane3, finding minimum roundtrip time"
|
||||
|
||||
** Note: The sampled data has been shifted by timA. The preamble is now
|
||||
in phase. **
|
||||
|
||||
## Fine adjustment
|
||||
|
||||
As timA still points the middle of the data symbol an offset of 32 is added.
|
||||
It now points the falling edge of the preamble.
|
||||
The fine adjustment is to reduce errors introduced by jitter. The phase is
|
||||
adjusted from `timA - 25` to `timA + 25` and the DQS signal is sampled 100
|
||||
times. The fine adjustment finds the middle of each rising edge (it's actual
|
||||
the falling edge of the preamble) to get the final IO phase. You can see the
|
||||
result in the picture below.
|
||||
|
||||
![alt text][timA_lane0-3_adjust_fine]
|
||||
|
||||
[timA_lane0-3_adjust_fine]: timA_lane0-3_adjust_fine.png "timA for lane0 - lane3, fine adjustment"
|
||||
|
||||
Lanes 0 - 2 will be adjusted by a phase of -10, while lane 3 is already correct.
|
||||
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
|
Before Width: | Height: | Size: 98 KiB After Width: | Height: | Size: 98 KiB |
|
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
|
Before Width: | Height: | Size: 102 KiB After Width: | Height: | Size: 102 KiB |
|
Before Width: | Height: | Size: 103 KiB After Width: | Height: | Size: 103 KiB |
@@ -148,6 +148,7 @@ mv build/coreboot.rom.new build/coreboot.rom
|
||||
<li>Edit the src/soc/<Vendor>/<Chip Family>/memmap.c file
|
||||
<ol type="A">
|
||||
<li>Add the fsp/memmap.h include file</li>
|
||||
<li>Add the mmap_region_granularity routine</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add the necessary .h files to define the necessary values and structures</li>
|
||||
@@ -233,6 +234,8 @@ Use the following steps to locate the FSP binary:
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc">src/drivers/intel/fsp1_1/cache_as_ram.inc</a>
|
||||
</li>
|
||||
<li>Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common
|
||||
specifically building
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/intel/common/util.c">util.c</a>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
@@ -513,7 +516,7 @@ Use the following steps to debug the call to TempRamInit:
|
||||
a "struct pci_operations" that specifies a routine to set the subsystem
|
||||
IDs for the device. The routine might look something like this:
|
||||
</p>
|
||||
<pre><code>static void pci_set_subsystem(struct device *dev, unsigned vendor, unsigned device)
|
||||
<pre><code>static void pci_set_subsystem(device_t dev, unsigned vendor, unsigned device)
|
||||
{
|
||||
if (!vendor || !device) {
|
||||
vendor = pci_read_config32(dev, PCI_VENDOR_ID);
|
||||
@@ -535,7 +538,7 @@ Use the following steps to debug the call to TempRamInit:
|
||||
The memory map is built by the various PCI device drivers during the
|
||||
BS_DEV_RESOURCES state of ramstage. The northcluster driver will typically
|
||||
specify the DRAM resources while the other drivers will typically specify
|
||||
the IO resources. These resources are hung off the struct device *data structure by
|
||||
the IO resources. These resources are hung off the device_t data structure by
|
||||
src/device/device_util.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device_util.c;hb=HEAD#l448">new_resource</a>.
|
||||
</p>
|
||||
<p>
|
||||
@@ -657,7 +660,7 @@ Use the following steps to debug the call to TempRamInit:
|
||||
The EDK2 data structure is defined in
|
||||
MdeModulePkg/Include/IndustryStandard/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandard/Acpi61.h#l111">Acpi61.h</a>
|
||||
The coreboot data structure is defined in
|
||||
src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/acpi/acpi.h;hb=HEAD#l237">acpi.h</a>
|
||||
src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/acpi.h;hb=HEAD#l237">acpi.h</a>
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
@@ -667,7 +670,7 @@ Use the following steps to debug the call to TempRamInit:
|
||||
</li>
|
||||
<li>Create a acpi.c module:
|
||||
<ol type="A">
|
||||
<li>Add the acpi_fill_fadt routine and initialize the values above</li>
|
||||
<li>Add the acpi_fill_in_fadt routine and initialize the values above</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
@@ -264,7 +264,7 @@
|
||||
<ul>
|
||||
<li>MemoryInit UPD values are correct</li>
|
||||
<li>MemoryInit returns 0 (success) and</li>
|
||||
<li>The message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
<li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
is not displayed
|
||||
</li>
|
||||
</ul>
|
||||
@@ -324,7 +324,7 @@
|
||||
<ul>
|
||||
<li>MemoryInit UPD values are correct</li>
|
||||
<li>MemoryInit returns 0 (success) and</li>
|
||||
<li>The message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
<li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
is not displayed
|
||||
</li>
|
||||
</ul>
|
||||
@@ -374,4 +374,4 @@
|
||||
<hr>
|
||||
<p>Modified: 4 March 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
@@ -29,6 +29,7 @@
|
||||
</li>
|
||||
<li><a target="_blank" href="SoC/soc.html">SoC</a> support</li>
|
||||
<li><a target="_blank" href="Board/board.html">Board</a> support</li>
|
||||
<li><a target="_blank" href="vboot.html">Verified Boot (vboot)</a> support</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
402
Documentation/Intel/vboot.html
Normal file
402
Documentation/Intel/vboot.html
Normal file
@@ -0,0 +1,402 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>vboot - Verified Boot Support</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>vboot - Verified Boot Support</h1>
|
||||
|
||||
<p>
|
||||
Google's verified boot support consists of:
|
||||
</p>
|
||||
<ul>
|
||||
<li>A root of trust</li>
|
||||
<li>Special firmware layout</li>
|
||||
<li>Firmware verification</li>
|
||||
<li>Firmware measurements</li>
|
||||
<li>A firmware update mechanism</li>
|
||||
<li>Specific build flags</li>
|
||||
<li>Signing the coreboot image</li>
|
||||
</ul>
|
||||
|
||||
Google's vboot verifies the firmware and places measurements
|
||||
within the TPM.
|
||||
|
||||
<hr>
|
||||
<h2>Root of Trust</h2>
|
||||
<p>
|
||||
When using vboot, the root-of-trust is basically the read-only portion of the
|
||||
SPI flash. The following items factor into the trust equation:
|
||||
</p>
|
||||
<ul>
|
||||
<li>The GCC compiler must reliably translate the code into machine code
|
||||
without inserting any additional code (virus, backdoor, etc.)
|
||||
</li>
|
||||
<li>The CPU must reliably execute the reset sequence and instructions as
|
||||
documented by the CPU manufacturer.
|
||||
</li>
|
||||
<li>The SPI flash must provide only the code programmed into it to the CPU
|
||||
without providing any alternative reset vector or code sequence.
|
||||
</li>
|
||||
<li>The SPI flash must honor the write-protect input and protect the
|
||||
specified portion of the SPI flash from all erase and write accesses.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The firmware is typically protected using the write-protect pin on the SPI
|
||||
flash part and setting some of the write-protect bits in the status register
|
||||
during manufacturing. The protected area is platform specific and for x86
|
||||
platforms is typically 1/4th of the SPI flash
|
||||
part size. Because this portion of the SPI flash is hardware write protected,
|
||||
it is not possible to update this portion of the SPI flash in the field,
|
||||
without altering the system to eliminate the ground connection to the SPI flash
|
||||
write-protect pin. Without hardware modifications, this portion of the SPI
|
||||
flash maintains the manufactured state during the system's lifetime.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2>Firmware Layout</h2>
|
||||
<p>
|
||||
Several sections are added to the firmware layout to support vboot:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Read-only section</li>
|
||||
<li>Google Binary Blob (GBB) area</li>
|
||||
<li>Read/write section A</li>
|
||||
<li>Read/write section B</li>
|
||||
</ul>
|
||||
<p>
|
||||
The following sections describe the various portions of the flash layout.
|
||||
</p>
|
||||
|
||||
<h3>Read-Only Section</h3>
|
||||
<p>
|
||||
The read-only section contains a coreboot file system (CBFS) that contains all
|
||||
of the boot firmware necessary to perform recovery for the system. This
|
||||
firmware is typically protected using the write-protect pin on the SPI flash
|
||||
part and setting some of the write-protect bits in the status register during
|
||||
manufacturing. The protected area is typically 1/4th of the SPI flash part
|
||||
size and must cover the entire read-only section which consists of:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Vital Product Data (VPD) area</li>
|
||||
<li>Firmware ID area</li>
|
||||
<li>Google Binary Blob (GBB) area</li>
|
||||
<li>coreboot file system containing read-only recovery firmware</li>
|
||||
</ul>
|
||||
|
||||
<h3>Google Binary Blob (GBB) Area</h3>
|
||||
<p>
|
||||
The GBB area is part of the read-only section. This area contains a 4096 or
|
||||
8192 bit public root RSA key that is used to verify the VBLOCK area to obtain
|
||||
the firmware signing key.
|
||||
</p>
|
||||
|
||||
<h3>Recovery Firmware</h3>
|
||||
<p>
|
||||
The recovery firmware is contained within a coreboot file system and consists
|
||||
of:
|
||||
</p>
|
||||
<ul>
|
||||
<li>reset vector</li>
|
||||
<li>bootblock</li>
|
||||
<li>verstage</li>
|
||||
<li>romstage</li>
|
||||
<li>postcar</li>
|
||||
<li>ramstage</li>
|
||||
<li>payload</li>
|
||||
<li>flash map file</li>
|
||||
<li>config file</li>
|
||||
<li>processor specific files:
|
||||
<ul>
|
||||
<li>Microcode</li>
|
||||
<li>fspm.bin</li>
|
||||
<li>fsps.bin</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The recovery firmware is written during manufacturing and typically contains
|
||||
code to write the storage device (eMMC device or hard disk). The recovery
|
||||
image is usually contained on a socketed device such as a USB flash drive or
|
||||
an SD card. Depending upon the payload firmware doing the recovery, it may
|
||||
be possible for the user to interact with the system to specify the recovery
|
||||
image path. Part of the recovery is also to write the A and B areas of the
|
||||
SPI flash device to boot the system.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Read/Write Section</h3>
|
||||
|
||||
<p>
|
||||
The read/write sections contain an area which contains the firmware signing
|
||||
key and signature and an area containing a coreboot file system with a subset
|
||||
of the firmware. The firmware files in FW_MAIN_A and FW_MAIN_B are:
|
||||
</p>
|
||||
<ul>
|
||||
<li>romstage</li>
|
||||
<li>postcar</li>
|
||||
<li>ramstage</li>
|
||||
<li>payload</li>
|
||||
<li>config file</li>
|
||||
<li>processor specific files:
|
||||
<ul>
|
||||
<li>Microcode</li>
|
||||
<li>fspm.bin</li>
|
||||
<li>fsps.bin</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The firmware subset enables most issues to be fixed in the field with firmware
|
||||
updates. The firmware files handle memory and most of silicon initialization.
|
||||
These files also produce the tables which get passed to the operating system.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2>Firmware Updates</h2>
|
||||
<p>
|
||||
The read/write sections exist in one of three states:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Invalid</li>
|
||||
<li>Ready to boot</li>
|
||||
<li>Successfully booted</li>
|
||||
</ul>
|
||||
|
||||
<table border="1">
|
||||
<tr bgcolor="#ffc0c0">
|
||||
<td>
|
||||
Where is this state information written?
|
||||
<br/>CMOS?
|
||||
<br/>RW_NVRAM?
|
||||
<br/>RW_FWID_*
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
Firmware updates are handled by the operating system by writing any read/write
|
||||
section that is not in the "successfully booted" state. Upon the next reboot,
|
||||
vboot determines the section to boot. If it finds one in the "ready to boot"
|
||||
state then it attempts to boot using that section. If the boot fails then
|
||||
vboot marks the section as invalid and attempts to fall back to a read/write
|
||||
section in the "successfully booted" state. If vboot is not able to find a
|
||||
section in the "successfully booted" state then vboot enters recovery mode.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Only the operating system is able to transition a section from the "ready to
|
||||
boot" state to the "successfully booted" state. The transition is typically
|
||||
done after the operating system has been running for a while indicating
|
||||
that successful boot was possible and the operating system is stable.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Note that as long as the SPI write protection is in place then the system is
|
||||
always recoverable. If the flash update fails then the system will continue
|
||||
to boot using the previous read/write area. The same is true if coreboot
|
||||
passes control to the payload or the operating system and then the boot fails.
|
||||
In the worst case, the SPI flash gets totally corrupted in which case vboot
|
||||
fails the signature checks and enters recovery mode. There are no times where
|
||||
the SPI flash is exposed and the reset vector or part of the recovery firmware
|
||||
gets corrupted.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2>Build Flags</h2>
|
||||
<p>
|
||||
The following Kconfig values need to be selected to enable vboot:
|
||||
</p>
|
||||
<ul>
|
||||
<li>COLLECT_TIMESTAMPS</li>
|
||||
<li>VBOOT</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The starting stage needs to be specified by selecting either
|
||||
VBOOT_STARTS_IN_BOOTBLOCK or VBOOT_STARTS_IN_ROMSTAGE.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If vboot starts in bootblock then vboot may be built as a separate stage by
|
||||
selecting VBOOT_SEPARATE_VERSTAGE. Additionally, if static RAM is too small
|
||||
to fit both verstage and romstage then selecting VBOOT_RETURN_FROM_VERSTAGE
|
||||
enables bootblock to reuse the RAM occupied by verstage for romstage.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Non-volatile flash is needed for vboot operation. This flash area may be in
|
||||
CMOS, the EC, or in a read/write area of the SPI flash device. Select one of
|
||||
the following:
|
||||
</p>
|
||||
<ul>
|
||||
<li>VBOOT_VBNV_CMOS</li>
|
||||
<li>VBOOT_VBNV_EC</li>
|
||||
<li>VBOOT_VBNV_FLASH</li>
|
||||
</ul>
|
||||
<p>
|
||||
More non-volatile storage features may be found in src/vboot/Kconfig.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A TPM is also required for vboot operation. TPMs are available in
|
||||
drivers/i2c/tpm and drivers/pc80/tpm.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In addition to adding the coreboot files into the read-only region, enabling
|
||||
vboot causes the build script to add the read/write files into coreboot file
|
||||
systems in FW_MAIN_A and FW_MAIN_B.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2>Signing the coreboot Image</h2>
|
||||
<p>
|
||||
The following command script is an example of how to sign the coreboot image file.
|
||||
This script is used on the Intel Galileo board and creates the GBB area and
|
||||
inserts it into the coreboot image. It also updates the VBLOCK areas with the
|
||||
firmware signing key and the signature for the FW_MAIN firmware. More details
|
||||
are available in 3rdparty/vboot/README.
|
||||
</p>
|
||||
|
||||
<pre><code>#!/bin/sh
|
||||
#
|
||||
# The necessary tools were built and installed using the following commands:
|
||||
#
|
||||
# pushd 3rdparty/vboot
|
||||
# make
|
||||
# sudo make install
|
||||
# popd
|
||||
#
|
||||
# The keys were made using the following command
|
||||
#
|
||||
# 3rdparty/vboot/scripts/keygeneration/create_new_keys.sh \
|
||||
# --4k --4k-root --output $PWD/keys
|
||||
#
|
||||
#
|
||||
# The "magic" numbers below are derived from the GBB section in
|
||||
# src/mainboard/intel/galileo/vboot.fmd.
|
||||
#
|
||||
# GBB Header Size: 0x80
|
||||
# GBB Offset: 0x611000, 4KiB block number: 1553 (0x611)
|
||||
# GBB Length: 0x7f000, 4KiB blocks: 127 (0x7f)
|
||||
# COREBOOT Offset: 0x690000, 4KiB block number: 1680 (0x690)
|
||||
# COREBOOT Length: 0x170000, 4KiB blocks: 368 (0x170)
|
||||
#
|
||||
# 0x7f000 (GBB Length) = 0x80 + 0x100 + 0x1000 + 0x7ce80 + 0x1000
|
||||
#
|
||||
# Create the GBB area blob
|
||||
# Parameters: hwid_size,rootkey_size,bmpfv_size,recoverykey_size
|
||||
#
|
||||
gbb_utility -c 0x100,0x1000,0x7ce80,0x1000 gbb.blob
|
||||
|
||||
#
|
||||
# Copy from the start of the flash to the GBB region into the signed flash
|
||||
# image.
|
||||
#
|
||||
# 1553 * 4096 = 0x611 * 0x1000 = 0x611000, size of area before GBB
|
||||
#
|
||||
dd conv=fdatasync ibs=4096 obs=4096 count=1553 \
|
||||
if=build/coreboot.rom of=build/coreboot.signed.rom
|
||||
|
||||
#
|
||||
# Append the empty GBB area to the coreboot.rom image.
|
||||
#
|
||||
# 1553 * 4096 = 0x611 * 0x1000 = 0x611000, offset to GBB
|
||||
#
|
||||
dd conv=fdatasync obs=4096 obs=4096 seek=1553 if=gbb.blob \
|
||||
of=build/coreboot.signed.rom
|
||||
|
||||
#
|
||||
# Append the rest of the read-only region into the signed flash image.
|
||||
#
|
||||
# 1680 * 4096 = 0x690 * 0x1000 = 0x690000, offset to COREBOOT area
|
||||
# 368 * 4096 = 0x170 * 0x1000 = 0x170000, length of COREBOOT area
|
||||
#
|
||||
dd conv=fdatasync ibs=4096 obs=4096 skip=1680 seek=1680 count=368 \
|
||||
if=build/coreboot.rom of=build/coreboot.signed.rom
|
||||
|
||||
#
|
||||
# Insert the HWID and public root and recovery RSA keys into the GBB area.
|
||||
#
|
||||
gbb_utility \
|
||||
--set --hwid='Galileo' \
|
||||
-r $PWD/keys/recovery_key.vbpubk \
|
||||
-k $PWD/keys/root_key.vbpubk \
|
||||
build/coreboot.signed.rom
|
||||
|
||||
#
|
||||
# Sign the read/write firmware areas with the private signing key and update
|
||||
# the VBLOCK_A and VBLOCK_B regions.
|
||||
#
|
||||
3rdparty/vboot/scripts/image_signing/sign_firmware.sh \
|
||||
build/coreboot.signed.rom \
|
||||
$PWD/keys \
|
||||
build/coreboot.signed.rom
|
||||
</code></pre>
|
||||
|
||||
<hr>
|
||||
<h2>Boot Flow</h2>
|
||||
<p>
|
||||
The reset vector exist in the read-only area and points to the bootblock entry
|
||||
point. The only copy of the bootblock exists in the read-only area of the SPI
|
||||
flash. Verstage may be part of the bootblock or a separate stage. If separate
|
||||
then the bootblock loads verstage from the read-only area and transfers control
|
||||
to it.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Upon first boot, verstage attempts to verify the read/write section A. It gets
|
||||
the public root key from the GBB area and uses that to verify the VBLOCK area
|
||||
in read-write section A. If the VBLOCK area is valid then it extracts the
|
||||
firmware signing key (1024-8192 bits) and uses that to verify the FW_MAIN_A
|
||||
area of read/write section A. If the verification is successful then verstage
|
||||
instructs coreboot to use the coreboot file system in read/write section A for
|
||||
the contents of the remaining boot firmware (romstage, postcar, ramstage and
|
||||
the payload).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If verification fails for the read/write area and the other read/write area is
|
||||
not valid vboot falls back to the read-only area to boot into system recovery.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2>Chromebook Special Features</h2>
|
||||
<p>
|
||||
Google's Chromebooks have some special features:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Developer mode</li>
|
||||
<li>Write-protect screw</li>
|
||||
</ul>
|
||||
|
||||
<h3>Developer Mode</h3>
|
||||
<p>
|
||||
Developer mode allows the user to use coreboot to boot another operating system.
|
||||
This may be a another (beta) version of Chrome OS, or another flavor of
|
||||
GNU/Linux. Use of developer mode does not void the system warranty. Upon
|
||||
entry into developer mode, all locally saved data on the system is lost.
|
||||
This prevents someone from entering developer mode to subvert the system
|
||||
security to access files on the local system or cloud.
|
||||
</p>
|
||||
|
||||
<h3>Write Protect Screw</h3>
|
||||
<p>
|
||||
Chromebooks have a write-protect screw which provides the ground to the
|
||||
write-protect pin of the SPI flash. Google specifically did this to allow
|
||||
the manufacturing line and advanced developers to re-write the entire SPI flash
|
||||
part. Once the screw is removed, any firmware may be placed on the device.
|
||||
However, accessing this screw requires opening the case and voids the system
|
||||
warranty!
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<p>Modified: 2 May 2017</p>
|
||||
</body>
|
||||
</html>
|
||||
480
Documentation/Kconfig.tex
Normal file
480
Documentation/Kconfig.tex
Normal file
@@ -0,0 +1,480 @@
|
||||
\documentclass[10pt,letterpaper]{article}
|
||||
\usepackage[latin1]{inputenc}
|
||||
\usepackage{amsmath}
|
||||
\usepackage{amsfonts}
|
||||
\usepackage{amssymb}
|
||||
\author{Ron Minnich}
|
||||
\title{Kconfig usage in coreboot v2}
|
||||
\begin{document}
|
||||
\section{Introduction}
|
||||
This document describes how to use Kconfig in v2. We describe our usage of Kconfig files, Makefile.inc files, when and where to use them, how to use them, and, interestingly, when and where not to use them.
|
||||
\section{Kconfig variations}
|
||||
Most Kconfig files set variables, which can be set as part of the Kconfig dialog. Not all Kconfig variables are set by the user, however; some are too dangerous. These are merely enabled by the mainboard.
|
||||
|
||||
For variables set by the user, see src/console/Kconfig.
|
||||
|
||||
For variables not set by the user, see src/mainboard/amd/serengeti\_cheetah/Kconfig. Users should never set such variables as the cache as RAM base. These are highly mainboard dependent.
|
||||
|
||||
Kconfig files use the source command to include subdirectories. In most cases, save for limited cases described below, subdirectories have Kconfig files. They are always sourced unconditionally.
|
||||
|
||||
\section{Makefile and Makefile.inc}
|
||||
There is only one Makefile, at the top level. All other makefiles are included as Makefile.inc. All the next-level Makefile.inc files are selected in the top level Makefile. Directories that are platform-independent are in BUILD-y; platform-dependent (e.g. Makefile.inc's that depend on architecture) are included in PLATFORM-y.
|
||||
|
||||
Make is not recursive. There is only one make process.
|
||||
\subsection{subdirs usage}
|
||||
Further includes of Makefile.inc, if needed, are done via subdirs-y commands. As in Linux, the subdirs can be conditional or unconditional. Conditional includes are done via subdirs-\$(CONFIG\_VARIABLE) usage; unconditional are done via subdirs-y.
|
||||
|
||||
We define the common rules for which variation to use below.
|
||||
\subsection{object file specification}
|
||||
There are several different types of objects specified in the tree. They are:
|
||||
\begin{description}
|
||||
\item[obj]objects for the RAM part of the code
|
||||
\item[driver]drivers for the RAM part. Drivers are not represented in the device tree but do have a driver struct attached in the driver section.
|
||||
\item[initobj]seperately-compiled code for the ROM section of coreboot
|
||||
\end{description}
|
||||
These items are specified via the -y syntax as well. Conditional object inclusion is done via the -\$(CONFIG\_VARIABLE) syntax.
|
||||
|
||||
\section{Example: AMD serengeti cheetah}
|
||||
\subsection{mainboard/Kconfig}
|
||||
Defines Vendor variables. Currently defined variables are:
|
||||
Sources all Kconfig files in the vendor directories.
|
||||
\input{ mainboardkconfig.tex}
|
||||
\subsection{mainboard/Makefile.inc}
|
||||
There is none at this time.
|
||||
\subsection{mainboard/$<$vendor$>$/Kconfig}
|
||||
We use the amd as a model. The only action currently taken is to source all Kconfig's in the
|
||||
subdirectories.
|
||||
\subsection{mainboard/$<$vendor$>$/Makefile.inc}
|
||||
We use amd as a model. There is currently no Makefile.inc at this level.
|
||||
\subsection{mainboard/$<$vendor$>$/$<$board$>$/Kconfig}
|
||||
The mainboard Kconfig and Makefile.inc are designed to be the heart of the build. The defines
|
||||
and rules in here determine everything about how a mainboard target is built.
|
||||
We will use serengeti\_cheetah as a model. It defines these variables.
|
||||
\input{ mainboardkconfig.tex}
|
||||
\subsection{mainboard/$<$vendor$>$/$<$board$>$/Makefile.inc}
|
||||
This is a fairly complex Makefile.inc. Because this is such a critical component, we are going to excerpt and take it piece by piece.
|
||||
Note that this is the mainboard as of August, 2009, and it may change over time.
|
||||
\subsubsection{objects}
|
||||
We define objects in the first part. The mainbard itself is a driver and included unconditionally. Other objects are conditional:
|
||||
\begin{verbatim}
|
||||
driver-y += mainboard.o
|
||||
|
||||
#needed by irq_tables and mptable and acpi_tables
|
||||
obj-y += get_bus_conf.o
|
||||
obj-$(CONFIG_HAVE_MP_TABLE) += mptable.o
|
||||
obj-$(CONFIG_HAVE_PIRQ_TABLE) += irq_tables.o
|
||||
obj-$(CONFIG_HAVE_ACPI_TABLES) += dsdt.o
|
||||
obj-$(CONFIG_HAVE_ACPI_TABLES) += acpi_tables.o
|
||||
obj-$(CONFIG_HAVE_ACPI_TABLES) += fadt.o
|
||||
|
||||
#./ssdt.o is in northbridge/amd/amdk8/Config.lb
|
||||
obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt2.o
|
||||
obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt3.o
|
||||
obj-$(CONFIG_HAVE_ACPI_TABLES) += ssdt4.o
|
||||
driver-y += ../../../drivers/i2c/i2cmux/i2cmux.o
|
||||
|
||||
# This is part of the conversion to init-obj and away from included code.
|
||||
|
||||
initobj-y += crt0.o
|
||||
\end{verbatim}
|
||||
\subsubsection{romcc legacy support}
|
||||
We hope to move away from romcc soon, but for now, if one is using romcc, the Makefile.inc must define
|
||||
crt0 include files (assembly code for startup, usually); and several ldscripts. These are taken directly from the
|
||||
old Config.lb. Note that these use the -y syntax and can use the ability to be included conditionally.
|
||||
\begin{verbatim}
|
||||
crt0-y += ../../../../src/cpu/x86/16bit/entry16.inc
|
||||
crt0-y += ../../../../src/cpu/x86/32bit/entry32.inc
|
||||
crt0-y += ../../../../src/cpu/x86/16bit/reset16.inc
|
||||
crt0-y += ../../../../src/arch/i386/lib/id.inc
|
||||
crt0-y += ../../../../src/cpu/amd/car/cache_as_ram.inc
|
||||
crt0-y += auto.inc
|
||||
|
||||
ldscript-y += ../../../../src/arch/i386/init/ldscript_fallback_cbfs.lb
|
||||
ldscript-y += ../../../../src/cpu/x86/16bit/entry16.lds
|
||||
ldscript-y += ../../../../src/cpu/x86/16bit/reset16.lds
|
||||
ldscript-y += ../../../../src/arch/i386/lib/id.lds
|
||||
ldscript-y += ../../../../src/arch/i386/lib/failover.lds
|
||||
|
||||
\end{verbatim}
|
||||
\subsubsection{POST\_EVALUATION}
|
||||
POST\_EVALUATION rules should be placed after this section:
|
||||
\begin{verbatim}
|
||||
ifdef POST_EVALUATION
|
||||
\end{verbatim}
|
||||
to ensure that the values of variables are correct.
|
||||
Here are the post-evaluation rules for this mainboard:
|
||||
\begin{verbatim}
|
||||
$(obj)/dsdt.c: $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
|
||||
iasl -p dsdt -tc $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
|
||||
mv dsdt.hex $@
|
||||
|
||||
$(obj)/mainboard/$(MAINBOARDDIR)/dsdt.o: $(obj)/dsdt.c
|
||||
$(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c $< -o $@
|
||||
|
||||
$(obj)/ssdt2.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci2.asl
|
||||
iasl -p $(CURDIR)/pci2 -tc $(CONFIG_MAINBOARD)/dx/pci2.asl
|
||||
perl -pi -e 's/AmlCode/AmlCode_ssdt2/g' pci2.hex
|
||||
mv pci2.hex ssdt2.c
|
||||
|
||||
$(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl"
|
||||
iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/
|
||||
perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex
|
||||
mv pci3.hex ssdt3.c
|
||||
|
||||
$(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl"
|
||||
iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl
|
||||
perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex
|
||||
mv pci4.hex ssdt4.c
|
||||
|
||||
$(obj)/mainboard/$(MAINBOARDDIR)/auto.inc: $(src)/mainboard/$(MAINBOARDDIR)/rom.c $(obj)/option_table.h
|
||||
$(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c -S $(src)/mainboard/$(MAINBOARDDIR)/rom.c -o $@
|
||||
perl -e 's/\.rodata/.rom.data/g' -pi $@
|
||||
perl -e 's/\.text/.section .rom.text/g' -pi $@
|
||||
|
||||
\end{verbatim}
|
||||
The last rule is for romcc, and, again, we hope to eliminate romcc usage and this rule soon. The first set of rules concern ACPI tables.
|
||||
\subsubsection{devicetree.cb}
|
||||
Most of the old Config.lb is gone, but one piece remains: the device tree specification. This tree is still required to build a mainboard
|
||||
properly, as it defines topology and chips that can be defined no other way.
|
||||
Let's go through the tree.
|
||||
\begin{verbatim}
|
||||
chip northbridge/amd/amdk8/root_complex
|
||||
device cpu_cluster 0 on
|
||||
chip cpu/amd/socket_F
|
||||
device lapic 0 on end
|
||||
end
|
||||
end
|
||||
\end{verbatim}
|
||||
This topology is always somewhat confusing to newcomers, and even to coreboot veterans.
|
||||
|
||||
We root the tree at the pci-e {\it root complex}. There is always the question of how and where to root the tree. Over the years we
|
||||
have found that the one part that never goes away is the root complex. CPU sockets may be empty or full; but there is always a northbridge
|
||||
somewhere, since it runs memory.
|
||||
|
||||
|
||||
What is the APIC? Northbridges always have an Advanced Programmable Interrupt Controller, and that {\it APIC cluster} is a topological connection to the
|
||||
CPU socket. So the tree is rooted at the northbridge, which has a link to a CPU cluster, and then the CPU. The CPU contains
|
||||
its own APIC, and will define any parameters needed. In this case, we have a northbridge of type
|
||||
{\it northbridge/amd/amdk8/root\_complex}, with its own cpu\_cluster device which we turn on,
|
||||
which connects to a {\it cpu/amd/socket\_F},
|
||||
which has a local apic, which is on.
|
||||
|
||||
Note that we do not enumerate all CPUs, even on this SMP mainboard. The reason is they may not all be there. The CPU we define here
|
||||
is the so-called Boot Strap Processor, or BSP; the other CPUs will come along later, as the are discovered. We do not require (unlike many
|
||||
BIOSes) that the BSP be CPU 0; any CPU will do.
|
||||
\begin{verbatim}
|
||||
device domain 0 on
|
||||
chip northbridge/amd/amdk8
|
||||
device pci 18.0 on # northbridge
|
||||
# devices on link 0, link 0 == LDT 0
|
||||
\end{verbatim}
|
||||
Here begins the pci domain, which usually starts with 0. Then there is the northbridge, which bridges to the PCI bus. On
|
||||
Opterons, certain CPU control registers are managed in PCI config space in device 18.0 (BSP), 19.0 (AP), and up.
|
||||
\begin{verbatim}
|
||||
chip southbridge/amd/amd8132
|
||||
# the on/off keyword is mandatory
|
||||
device pci 0.0 on end
|
||||
device pci 0.1 on end
|
||||
device pci 1.0 on end
|
||||
device pci 1.1 on end
|
||||
end
|
||||
\end{verbatim}
|
||||
This is the 8132, a bridge to a secondary PCI bus.
|
||||
\begin{verbatim}
|
||||
chip southbridge/amd/amd8111
|
||||
# this "device pci 0.0" is the parent the next one
|
||||
# PCI bridge
|
||||
device pci 0.0 on
|
||||
device pci 0.0 on end
|
||||
device pci 0.1 on end
|
||||
device pci 0.2 off end
|
||||
device pci 1.0 off end
|
||||
end
|
||||
\end{verbatim}
|
||||
The 8111 is a bridge to other busses and to the legacy ISA devices such as superio.
|
||||
\begin{verbatim}
|
||||
device pci 1.0 on
|
||||
chip superio/winbond/w83627hf
|
||||
device pnp 2e.0 off # Floppy
|
||||
io 0x60 = 0x3f0
|
||||
irq 0x70 = 6
|
||||
drq 0x74 = 2
|
||||
end
|
||||
device pnp 2e.1 off # Parallel Port
|
||||
io 0x60 = 0x378
|
||||
irq 0x70 = 7
|
||||
end
|
||||
device pnp 2e.2 on # Com1
|
||||
io 0x60 = 0x3f8
|
||||
irq 0x70 = 4
|
||||
end
|
||||
device pnp 2e.3 off # Com2
|
||||
io 0x60 = 0x2f8
|
||||
irq 0x70 = 3
|
||||
end
|
||||
device pnp 2e.5 on # Keyboard
|
||||
io 0x60 = 0x60
|
||||
io 0x62 = 0x64
|
||||
irq 0x70 = 1
|
||||
irq 0x72 = 12
|
||||
end
|
||||
device pnp 2e.6 off # CIR
|
||||
io 0x60 = 0x100
|
||||
end
|
||||
device pnp 2e.7 off # GAME_MIDI_GIPO1
|
||||
io 0x60 = 0x220
|
||||
io 0x62 = 0x300
|
||||
irq 0x70 = 9
|
||||
end
|
||||
device pnp 2e.8 off end # GPIO2
|
||||
device pnp 2e.9 off end # GPIO3
|
||||
device pnp 2e.a off end # ACPI
|
||||
device pnp 2e.b on # HW Monitor
|
||||
io 0x60 = 0x290
|
||||
irq 0x70 = 5
|
||||
end
|
||||
end
|
||||
end
|
||||
\end{verbatim}
|
||||
The pnp refers to the many Plug N Play devices on a superio. 2e refers to the base I/O address of the superio, and the number following the
|
||||
2e (i.e. 2e.1) is the Logical Device Number, or LDN. Each LDN has a common configuration (base, irq, etc.) and these are set by the statements under the LDN.
|
||||
\begin{verbatim}
|
||||
device pci 1.1 on end
|
||||
device pci 1.2 on end
|
||||
\end{verbatim}
|
||||
More devices. These statements set up placeholders in the device tree.
|
||||
\begin{verbatim}
|
||||
device pci 1.3 on
|
||||
chip drivers/i2c/i2cmux # pca9556 smbus mux
|
||||
device i2c 18 on #0 pca9516 1
|
||||
chip drivers/generic/generic #dimm 0-0-0
|
||||
device i2c 50 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 0-0-1
|
||||
device i2c 51 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 0-1-0
|
||||
device i2c 52 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 0-1-1
|
||||
device i2c 53 on end
|
||||
end
|
||||
end
|
||||
device i2c 18 on #1 pca9516 2
|
||||
chip drivers/generic/generic #dimm 1-0-0
|
||||
device i2c 50 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-0-1
|
||||
device i2c 51 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-1-0
|
||||
device i2c 52 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-1-1
|
||||
device i2c 53 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-2-0
|
||||
device i2c 54 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-2-1
|
||||
device i2c 55 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-3-0
|
||||
device i2c 56 on end
|
||||
end
|
||||
chip drivers/generic/generic #dimm 1-3-1
|
||||
device i2c 57 on end
|
||||
end
|
||||
end
|
||||
end
|
||||
end # acpi
|
||||
\end{verbatim}
|
||||
These are the i2c devices.
|
||||
\begin{verbatim}
|
||||
device pci 1.5 off end
|
||||
device pci 1.6 off end
|
||||
\end{verbatim}
|
||||
More placeholders.
|
||||
\begin{verbatim}
|
||||
register "ide0_enable" = "1"
|
||||
register "ide1_enable" = "1"
|
||||
end
|
||||
end # device pci 18.0
|
||||
|
||||
\end{verbatim}
|
||||
These "register" commands set controls in the southbridge.
|
||||
\begin{verbatim}
|
||||
device pci 18.0 on end
|
||||
device pci 18.0 on end
|
||||
\end{verbatim}
|
||||
These are the other two hypertransport links.
|
||||
\begin{verbatim}
|
||||
device pci 18.1 on end
|
||||
device pci 18.2 on end
|
||||
device pci 18.3 on end
|
||||
\end{verbatim}
|
||||
The 18.1 devices are, again, northbridge control for various k8 functions.
|
||||
\begin{verbatim}
|
||||
end
|
||||
\end{verbatim}
|
||||
That's it for the BSP I/O and HT busses. Now we begin the AP busses. Not much here.
|
||||
\begin{verbatim}
|
||||
chip northbridge/amd/amdk8
|
||||
device pci 19.0 on # northbridge
|
||||
chip southbridge/amd/amd8151
|
||||
# the on/off keyword is mandatory
|
||||
device pci 0.0 on end
|
||||
device pci 1.0 on end
|
||||
end
|
||||
end # device pci 19.0
|
||||
|
||||
device pci 19.0 on end
|
||||
device pci 19.0 on end
|
||||
device pci 19.1 on end
|
||||
device pci 19.2 on end
|
||||
device pci 19.3 on end
|
||||
end
|
||||
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
\subsection{cpu socket}
|
||||
The CPU socket is the key link from mainboard to its CPUs. Since many models of CPU can go in a socket, the mainboard mentions only
|
||||
the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus
|
||||
of all defines and Makefile controls for building the CPU components of a board.
|
||||
|
||||
\subsubsection{ cpu/Kconfig}
|
||||
Defines variables. Current variables are:
|
||||
\input{cpukconfig.tex}
|
||||
Sources all Kconfig files in the vendor directories.
|
||||
\subsubsection{ cpu/Makefile.inc}
|
||||
Unconditionally sources all Makefile.inc in the vendor directories.
|
||||
|
||||
\subsection{cpu/$<$vendor$>$/Kconfig}
|
||||
The only action currently taken is to source all Kconfig's in the
|
||||
subdirectories.
|
||||
\subsection{cpu/$<$vendor$>$/Makefile.inc}
|
||||
{\em Conditionally} source the socket directories.
|
||||
Example:
|
||||
\begin{verbatim}
|
||||
subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F
|
||||
\end{verbatim}
|
||||
.
|
||||
CONFIG\_CPU\_AMD\_SOCKET\_F is set in a mainboard file.
|
||||
|
||||
\subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig}
|
||||
Set variables that relate to this {\em socket}, and {\em any models that plug into this socket}. Note that
|
||||
the socket, as much as possible, should control the models, because the models may plug into many sockets.
|
||||
Socket\_F currently sets:
|
||||
\input{socketfkconfig.tex}
|
||||
|
||||
It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced.
|
||||
|
||||
\subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig}
|
||||
CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that
|
||||
if needed.
|
||||
\subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc}
|
||||
The Makefile.inc {\em unconditionally} specifies drivers and objects to be included in the build. There is no conditional
|
||||
compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include {em all}
|
||||
objects, because it is not possible to determine at build time what options may be needed for a given model CPU.
|
||||
This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc.
|
||||
|
||||
\subsection{northbridge}
|
||||
\subsubsection{northbridge/Kconfig}
|
||||
No variables. Source all vendor directory Kconfigs.
|
||||
\subsubsection{northbridge/Makefile.inc}
|
||||
No variables. unconditionally include all vendor Makefile.inc
|
||||
\subsubsection{northbridge/$<$vendor$>$/Kconfig}
|
||||
No variables. Source all chip directory Kconfigs.
|
||||
\subsubsection{northbridge/$<$vendor$>$/Makefile.inc}
|
||||
No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
|
||||
is the name of the part, e.g.
|
||||
\begin{verbatim}
|
||||
subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8
|
||||
\end{verbatim}
|
||||
.
|
||||
\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
|
||||
Typically a small number of variables. One defines the part name. Here is an example
|
||||
of the variables defined for the K8.
|
||||
\begin{verbatim}
|
||||
config NORTHBRIDGE_AMD_AMDK8
|
||||
bool
|
||||
default n
|
||||
|
||||
config AGP_APERTURE_SIZE
|
||||
hex
|
||||
default 0x4000000
|
||||
\end{verbatim}
|
||||
\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
|
||||
Typically very small set of rules, and very simple.
|
||||
Since this file is already conditionally included,
|
||||
we don't need to test for the chipset CONFIG variable. We
|
||||
can therefore test other variables (which is part of the reason
|
||||
we set up conditional inclusion of this file, instead
|
||||
of unconditionally including it). Here is an example from AMD K8.
|
||||
Note that we can make a variable conditional on the ACPI tables.
|
||||
\begin{verbatim}
|
||||
driver-y += northbridge.o
|
||||
driver-y += misc_control.o
|
||||
obj-y += get_sblk_pci1234.o
|
||||
obj-$(CONFIG_HAVE_ACPI_TABLES) += amdk8_acpi.o
|
||||
\end{verbatim}
|
||||
|
||||
\subsection{southbridge}
|
||||
\subsubsection{southbridge/Kconfig}
|
||||
No variables. Source all vendor directory Kconfigs.
|
||||
\subsubsection{southbridge/Makefile.inc}
|
||||
No variables. {\em Unconditionally} include all vendor Makefile.inc
|
||||
\subsubsection{southbridge/$<$vendor$>$/Kconfig}
|
||||
No variables. Source all chip directory Kconfigs.
|
||||
\subsubsection{southbridge/$<$vendor$>$/Makefile.inc}
|
||||
No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
|
||||
is the name of the part, e.g.
|
||||
\begin{verbatim}
|
||||
subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111
|
||||
\end{verbatim}
|
||||
.
|
||||
\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
|
||||
Typically a small number of variables. One defines the part name. Here is an example
|
||||
of the variables defined for the K8.
|
||||
\begin{verbatim}
|
||||
config SOUTHBRIDGE_AMD_AMD8111
|
||||
bool
|
||||
default n
|
||||
|
||||
\end{verbatim}
|
||||
\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
|
||||
Typically very small set of rules, and very simple.
|
||||
Since this file is already conditionally included,
|
||||
we don't need to test for the chipset CONFIG variable. We
|
||||
can therefore test other variables (which is part of the reason
|
||||
we set up conditional inclusion of this file, instead
|
||||
of unconditionally including it). Here is an example from AMD 8111.
|
||||
No conditionals in this one yet.
|
||||
\begin{verbatim}
|
||||
driver-y += amd8111.o
|
||||
driver-y += amd8111_usb.o
|
||||
driver-y += amd8111_lpc.o
|
||||
driver-y += amd8111_ide.o
|
||||
driver-y += amd8111_acpi.o
|
||||
driver-y += amd8111_usb2.o
|
||||
driver-y += amd8111_ac97.o
|
||||
driver-y += amd8111_nic.o
|
||||
driver-y += amd8111_pci.o
|
||||
driver-y += amd8111_smbus.o
|
||||
obj-y += amd8111_reset.o
|
||||
\end{verbatim}
|
||||
|
||||
\subsubsection{vendor and part}
|
||||
\subsection{southbridge}
|
||||
\subsubsection{vendor and part}
|
||||
\subsection{superio}
|
||||
\subsection{drivers/i2c}
|
||||
This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed.
|
||||
To compile in one of these files, name the .o directory. E.g. in serengeti\_cheetah we have:
|
||||
\begin{verbatim}
|
||||
\end{verbatim}
|
||||
|
||||
\subsubsection{vendor and part}
|
||||
|
||||
\end{document}
|
||||
281
Documentation/Lesson2.md
Normal file
281
Documentation/Lesson2.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# coreboot Lesson 2: Submitting a patch to coreboot.org
|
||||
|
||||
## Part 1: Setting up an account at coreboot.org
|
||||
|
||||
If you already have an account, skip to Part 2.
|
||||
|
||||
Otherwise, go to <https://review.coreboot.org> in your preferred web browser.
|
||||
Select **Register** in the upper right corner.
|
||||
|
||||
Select the appropriate sign-in. For example, if you have a Google account,
|
||||
select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your
|
||||
username for the account will be the username of the account you used to
|
||||
sign-in with. (ex. your Google username).
|
||||
|
||||
## Part 2a: Set up RSA Private/Public Key
|
||||
|
||||
If you prefer to use an HTTP password instead, skip to Part 2b.
|
||||
|
||||
For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
|
||||
<https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)>
|
||||
and follow the instructions there. Then, skip to Part 3.
|
||||
|
||||
Additionally, that section of the Web site provides explanation on starting
|
||||
an ssh-agent, which may be particularly helpful for those who anticipate
|
||||
frequently uploading changes.
|
||||
|
||||
If you instead prefer to have review.coreboot.org specific instructions,
|
||||
follow the steps below. Note that this particular section may have the
|
||||
most up-to-date instructions.
|
||||
|
||||
If you do not have an RSA key set up on your account already (as is the case
|
||||
with a newly created account), follow the instructions below; otherwise,
|
||||
doing so could overwrite an existing key.
|
||||
|
||||
In the upper right corner, select your name and click on **Settings**.
|
||||
Select **SSH Public Keys** on the left-hand side.
|
||||
|
||||
In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa".
|
||||
|
||||
Make a passphrase -- remember this phrase. It will be needed whenever you use
|
||||
this RSA Public Key. **Note:** You might want to use a short password, or
|
||||
forego the password altogether as you will be using it very often.
|
||||
|
||||
Open "id_rsa.pub", copy all contents and paste into the textbox under
|
||||
"Add SSH Public Key" in the https://review.coreboot.org webpage.
|
||||
|
||||
## Part 2b: Setting up an HTTP Password
|
||||
|
||||
Alternatively, instead of using SSH keys, you can use an HTTP password. To do so,
|
||||
after you select your name and click on **Settings** on the left-hand side, rather
|
||||
than selecting **SSH Public Keys**, select **HTTP Password**.
|
||||
|
||||
Click **Generate Password**. This should fill the "Password" box with a password. Copy
|
||||
the password, and add the following to your $HOME/.netrc file:
|
||||
|
||||
machine review.coreboot.org login YourUserNameHere password YourPasswordHere
|
||||
|
||||
where YourUserNameHere is your username, and YourPasswordHere is the password you
|
||||
just generated.
|
||||
|
||||
## Part 3: Clone coreboot and configure it for submitting patches
|
||||
|
||||
Go to the **Projects** tab in the upper left corner and select **List**.
|
||||
From the dropdown menu that appears, select "coreboot".
|
||||
|
||||
If you are using SSH keys, select **ssh** from the tabs under "Project coreboot"
|
||||
and run the command that appears. This should prompt you for your id_rsa passphrase,
|
||||
if you previously set one.
|
||||
|
||||
If you are using HTTP, instead, select **http** from the tabs under "Project coreboot"
|
||||
and run the command that appears
|
||||
|
||||
After it finishes cloning, "cd coreboot" will take you into the local
|
||||
git repository. Run "make gitconfig" to set up the hooks and configurations.
|
||||
For example, you will be asked to run the following commands to set your
|
||||
username and email.
|
||||
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "Your Email"
|
||||
|
||||
## Part 4: Submit a commit
|
||||
|
||||
An easy first commit to make is fixing existing checkpatch errors and warnings
|
||||
in the source files. To see errors that are already present, build the files in
|
||||
the repository by running 'make lint' in the coreboot directory. Alternatively,
|
||||
if you want to run 'make lint' on a specific directory, run:
|
||||
|
||||
for file in $(git ls-files | grep src/amd/quadcore); do \
|
||||
util/lint/checkpatch.pl --file $file --terse; done
|
||||
|
||||
where <filepath> is the filepath of the directory (ex. src/cpu/amd/car).
|
||||
|
||||
Any changes made to files under the src directory are made locally,
|
||||
and can be submitted for review.
|
||||
|
||||
Once you finish making your desired changes, use the command line to stage
|
||||
and submit your changes. An alternative and potentially easier way to stage
|
||||
and submit commits is to use git cola, a graphical user interface for git. For
|
||||
instructions on how to do so, skip to Part 4b.
|
||||
|
||||
## Part 4a: Using the command line to stage and submit a commit
|
||||
|
||||
To use the command line to stage a commit, run
|
||||
|
||||
git add <filename>
|
||||
|
||||
where `filename` is the name of your file.
|
||||
|
||||
To commit the change, run
|
||||
|
||||
git commit -s
|
||||
|
||||
**Note:** The -s adds a signed-off-by line by the committer. Your commit should be
|
||||
signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
|
||||
what you set with git config earlier).
|
||||
|
||||
Running git commit first checks for any errors and warnings using lint. If
|
||||
there are any, you must go back and fix them before submitting your commit.
|
||||
You can do so by making the necessary changes, and then staging your commit again.
|
||||
|
||||
When there are no errors or warnings, your default text editor will open.
|
||||
This is where you will write your commit message.
|
||||
|
||||
The first line of your commit message is your commit summary. This is a brief
|
||||
one-line description of what you changed in the files using the template
|
||||
below:
|
||||
|
||||
<filepath>: Short description
|
||||
*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
|
||||
**Note:** It is good practice to use present tense in your descriptions
|
||||
and do not punctuate your summary.
|
||||
|
||||
Then hit Enter. The next paragraph should be a more in-depth explanation of the
|
||||
changes you've made to the files. Again, it is good practice to use present
|
||||
tense.
|
||||
*ex. Fix space prohibited between function name and open parenthesis,
|
||||
line over 80 characters, unnecessary braces for single statement blocks,
|
||||
space required before open brace errors and warnings.*
|
||||
|
||||
When you have finished writing your commit message, save and exit the text
|
||||
editor. You have finished committing your change. If, after submitting your
|
||||
commit, you wish to make changes to it, running "git commit --amend" allows
|
||||
you to take back your commit and amend it.
|
||||
|
||||
When you are done with your commit, run 'git push' to push your commit to
|
||||
coreboot.org. **Note:** To submit as a draft, use
|
||||
'git push origin HEAD:refs/drafts/master' Submitting as a draft means that
|
||||
your commit will be on coreboot.org, but is only visible to those you add
|
||||
as reviewers.
|
||||
|
||||
## Part 4b: Using git cola to stage and submit a commit
|
||||
|
||||
If git cola is not installed on your machine, see
|
||||
https://git-cola.github.io/downloads.html for download instructions.
|
||||
|
||||
After making some edits to src files, rather than run "git add," run
|
||||
'git cola' from the command line. You should see all of the files
|
||||
edited under "Modified".
|
||||
|
||||
In the textbox labeled "Commit summary" provide a brief one-line
|
||||
description of what you changed in the files according to the template
|
||||
below:
|
||||
|
||||
<filepath>: Short description
|
||||
*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
|
||||
**Note:** It is good practice to use present tense in your descriptions
|
||||
and do not punctuate your short description.
|
||||
|
||||
In the larger text box labeled 'Extended description...' provide a more
|
||||
in-depth explanation of the changes you've made to the files. Again, it
|
||||
is good practice to use present tense.
|
||||
*ex. Fix space prohibited between function name and open parenthesis,
|
||||
line over 80 characters, unnecessary braces for single statement blocks,
|
||||
space required before open brace errors and warnings.*
|
||||
|
||||
Then press Enter two times to move the cursor to below your description.
|
||||
To the left of the text boxes, there is an icon with an downward arrow.
|
||||
Press the arrow and select "Sign Off." Make sure that you are signing off
|
||||
with your name and email (i.e. **Your Name** **<Your Email>**, based on what
|
||||
you set with git config earlier).
|
||||
|
||||
Now, review each of your changes and mark either individual changes or
|
||||
an entire file as Ready to Commit by marking it as 'Staged'. To do
|
||||
this, select one file from the 'Modified' list. If you only want to
|
||||
submit particular changes from each file, then highlight the red and
|
||||
green lines for your changes, right click and select 'Stage Selected
|
||||
Lines'. Alternatively, if an entire file is ready to be committed, just
|
||||
double click on the file under 'Modified' and it will be marked as
|
||||
Staged.
|
||||
|
||||
Once the descriptions are done and all the edits you would like to
|
||||
commit have been staged, press 'Commit' on the right of the text
|
||||
boxes.
|
||||
|
||||
If the commit fails due to persisting errors, a text box will appear
|
||||
showing the errors. You can correct these errors within 'git cola' by
|
||||
right-clicking on the file in which the error occurred and selecting
|
||||
'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and
|
||||
'Stage' the corrected file again. It might be necessary to refresh
|
||||
'git cola' in order for the file to be shown under 'Modified' again.
|
||||
Note: Be sure to add any other changes that haven't already been
|
||||
explained in the extended description.
|
||||
|
||||
When ready, select 'Commit' again. Once all errors have been satisfied
|
||||
and the commit succeeds, move to the command line and run 'git push'.
|
||||
**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master'
|
||||
Submitting as a draft means that your commit will be on coreboot.org, but is
|
||||
only visible to those you add as reviewers.
|
||||
|
||||
## Part 5: Getting your commit reviewed
|
||||
|
||||
Your commits can now be seen on review.coreboot.org if you select “My”
|
||||
and click on “Changes” and can be reviewed by others. Your code will
|
||||
first be reviewed by build bot (Jenkins), which will either give you a warning
|
||||
or verify a successful build; if so, your commit will receive a +1. Other
|
||||
users may also give your commit +1. For a commit to be merged, it needs
|
||||
to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users
|
||||
can give a +2.
|
||||
|
||||
## Part 6 (optional): bash-git-prompt
|
||||
|
||||
To help make it easier to understand the state of the git repository
|
||||
without running 'git status' or 'git log', there is a way to make the
|
||||
command line show the status of the repository at every point. This
|
||||
is through bash-git-prompt.
|
||||
|
||||
Instructions for installing this are found at:
|
||||
https://github.com/magicmonty/bash-git-prompt
|
||||
**Note:** Feel free to search for different versions of git prompt,
|
||||
as this one is specific to bash.
|
||||
|
||||
Alternatively, follow the instructions below:
|
||||
Run the following two commands in the command line:
|
||||
|
||||
cd
|
||||
git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1
|
||||
|
||||
**Note:** cd will change your directory to your home directory, so the
|
||||
git clone command will be run there.
|
||||
|
||||
Finally, open the ~/.bashrc file and append the following two lines:
|
||||
|
||||
GIT_PROMPT_ONLY_IN_REPO=1
|
||||
source ~/.bash-git-prompt/gitprompt.sh
|
||||
|
||||
Now, whenever you are in a git repository, it will continuously display
|
||||
its state.
|
||||
|
||||
There also are additional configurations that you can change depending on your
|
||||
preferences. If you wish to do so, look at the "All configs for .bashrc" section
|
||||
on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
|
||||
various lines that you can copy, uncomment and add to your .bashrc file to
|
||||
change the configurations. Example configurations include avoid fetching remote
|
||||
status, and supporting versions of Git older than 1.7.10.
|
||||
|
||||
## Appendix: Miscellaneous Advice
|
||||
|
||||
### Updating a commit after running git push:
|
||||
|
||||
Suppose you would like to update a commit that has already been pushed to the
|
||||
remote repository. If the commit you wish to update is the most recent
|
||||
commit you have made, after making your desired changes, stage the files
|
||||
(either using git add or in git cola), and amend the commit. To do so,
|
||||
if you are using the command line, run "git commit --amend." If you are
|
||||
using git cola, click on the gear icon located on the upper left side under
|
||||
**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage
|
||||
the files you have changed, commit the changes, and run git push to push the
|
||||
changes to the remote repository. Your change should be reflected in Gerrit as
|
||||
a new patch set.
|
||||
|
||||
If, however, the commit you wish to update is not the most recent commit you
|
||||
have made, you will first need to checkout that commit. To do so, find the
|
||||
URL of the commit on <https://review.coreboot.org> and go to that page; if
|
||||
the commit is one that you previously pushed, it can be found by selecting
|
||||
**My** and then **Changes** in the upper left corner. To checkout this commit,
|
||||
in the upper right corner, click on **Download**, and copy the command listed
|
||||
next to checkout by clicking **Copy to clipboard**. Then, run the copied
|
||||
command in your coreboot repository. Now, the last commit should be the most
|
||||
recent commit to that patch; to update it, make your desired changes, stage
|
||||
the files, then amend and push the commit using the instructions in the above
|
||||
paragraph.
|
||||
@@ -7,7 +7,7 @@ PDFLATEX=pdflatex -t a4
|
||||
|
||||
FIGS=codeflow.pdf hypertransport.pdf
|
||||
|
||||
all: corebootPortingGuide.pdf
|
||||
all: corebootPortingGuide.pdf Kconfig.pdf
|
||||
|
||||
SVG2PDF=$(shell which svg2pdf)
|
||||
INKSCAPE=$(shell which inkscape)
|
||||
@@ -39,6 +39,30 @@ corebootPortingGuide.toc: $(FIGS) corebootBuildingGuide.tex
|
||||
corebootPortingGuide.pdf: $(FIGS) corebootBuildingGuide.tex corebootPortingGuide.toc
|
||||
$(PDFLATEX) corebootBuildingGuide.tex
|
||||
|
||||
Kconfig.pdf: Kconfig.tex mainboardkconfig.tex cpukconfig.tex socketfkconfig.tex
|
||||
$(PDFLATEX) $<
|
||||
|
||||
# quick, somebody! make me a macro!
|
||||
mainboardkconfig.tex: ../src/mainboard/Kconfig
|
||||
cat beginverbatim.tex > $@
|
||||
grep '^config' $< | awk '{print $2}' >>$@
|
||||
cat endverbatim.tex >> $@
|
||||
|
||||
skconfig.tex: ../src/mainboard/amd/serengeti_cheetah/Kconfig
|
||||
cat beginverbatim.tex > $@
|
||||
grep '^config' $< | awk '{print $2}' >>$@
|
||||
cat endverbatim.tex >> $@
|
||||
|
||||
cpukconfig.tex: ../src/cpu/Kconfig
|
||||
cat beginverbatim.tex > $@
|
||||
grep '^config' $< | awk '{print $2}' >>$@
|
||||
cat endverbatim.tex >> $@
|
||||
|
||||
socketfkconfig.tex: ../src/cpu/amd/socket_F/Kconfig
|
||||
cat beginverbatim.tex > $@
|
||||
grep '^config' $< | awk '{print $2}' >>$@
|
||||
cat endverbatim.tex >> $@
|
||||
|
||||
sphinx:
|
||||
$(MAKE) -f Makefile.sphinx html
|
||||
|
||||
@@ -46,10 +70,7 @@ clean-sphinx:
|
||||
$(MAKE) -f Makefile.sphinx clean
|
||||
|
||||
clean: clean-sphinx
|
||||
rm -f *.aux *.idx *.log *.toc *.out $(FIGS)
|
||||
rm -f *.aux *.idx *.log *.toc *.out $(FIGS) mainboardkconfig.tex skconfig.tex cpukconfig.tex socketfkconfig.tex
|
||||
|
||||
distclean: clean
|
||||
rm -f corebootPortingGuide.pdf
|
||||
|
||||
livesphinx:
|
||||
$(MAKE) -f Makefile.sphinx livehtml SPHINXOPTS="$(SPHINXOPTS)"
|
||||
rm -f corebootPortingGuide.pdf Kconfig.pdf
|
||||
|
||||
@@ -2,11 +2,10 @@
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXAUTOBUILD = sphinx-autobuild
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
@@ -47,7 +46,7 @@ help:
|
||||
|
||||
.PHONY: clean
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
.PHONY: html
|
||||
html:
|
||||
@@ -55,13 +54,6 @@ html:
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
.PHONY: livehtml
|
||||
livehtml:
|
||||
@echo "Starting sphinx-autobuild. The HTML pages are in $(BUILDDIR)."
|
||||
@echo "Press Ctrl-C to stop."
|
||||
@echo
|
||||
$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
|
||||
|
||||
.PHONY: dirhtml
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
|
||||
@@ -16,12 +16,6 @@ This is an (incomplete) list of POST codes emitted by coreboot v4.
|
||||
0x66 Devices have been enumerated
|
||||
0x88 Devices have been configured
|
||||
0x89 Devices have been enabled
|
||||
0xe0 Boot media (e.g. SPI ROM) is corrupt
|
||||
0xe1 Resource stored within CBFS is corrupt
|
||||
0xe2 Vendor binary (e.g. FSP) generated a fatal error
|
||||
0xe3 RAM could not be initialized
|
||||
0xe4 Critical hardware component could not initialize
|
||||
0xe5 Video subsystem failed to initialize
|
||||
0xf8 Entry into elf boot
|
||||
0xf3 Jumping to payload
|
||||
|
||||
|
||||
290
Documentation/RFC/config.tex
Normal file
290
Documentation/RFC/config.tex
Normal file
@@ -0,0 +1,290 @@
|
||||
New config language for LinuxBIOS
|
||||
|
||||
\begin{abstract}
|
||||
We describe the new configuration language for LinuxBIOS.
|
||||
\end{abstract}
|
||||
|
||||
\section{Scope}
|
||||
This document defines the new configuration language for LinuxBIOS.
|
||||
|
||||
\section{Goals}
|
||||
The goals of the new language are these:
|
||||
\begin{itemize}
|
||||
\item Simplified Makefiles so people can see what is set
|
||||
\item Move from the regular-expression-based language to something
|
||||
a bit more comprehensible and flexible
|
||||
\item make the specification easier for people to use and understand
|
||||
\item allow unique register-set-specifiers for each chip
|
||||
\item allow generic register-set-specifiers for each chip
|
||||
\item generate static initialization code, as needed, for the
|
||||
specifiers.
|
||||
\end{itemize}
|
||||
|
||||
\section{Language}
|
||||
Here is the new language. It is very similar to the old one, differing
|
||||
in only a few respects. It borrows heavily from Greg Watson's suggestions.
|
||||
|
||||
I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
|
||||
in '' are keywords; things in ``'' are strings in the actual text.
|
||||
\begin{verbatim}
|
||||
#exprs are composed of factor or factor + factor etc.
|
||||
expr ::= factor ( ``+'' factor | ``-'' factor | )*
|
||||
#factors are term or term * term or term / term or ...
|
||||
factor ::= term ( ``*'' term | ``/'' term | ... )*
|
||||
#
|
||||
unary-op ::= ``!'' ID
|
||||
# term is a number, hexnumber, ID, unary-op, or a full-blown expression
|
||||
term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
|
||||
|
||||
# Option command. Can be an expression or quote-string.
|
||||
# Options are used in the config tool itself (in expressions and 'if')
|
||||
# and are also passed to the C compiler when building linuxbios.
|
||||
# It is an error to have two option commands in a file.
|
||||
# It is an error to have an option command after the ID has been used
|
||||
# in an expression (i.e. 'set after used' is an error)
|
||||
option ::= 'option' ID '=' (``value'' | term)
|
||||
|
||||
# Default command. The ID is set to this value if no option command
|
||||
# is scanned.
|
||||
# Multiple defaults for an ID will produce warning, but not errors.
|
||||
# It is OK to scan a default command after use of an ID.
|
||||
# Options always over-ride defaults.
|
||||
default ::= 'default' ID '=' (``value'' | term)
|
||||
|
||||
# the mainboard, southbridge, northbridge commands
|
||||
# cause sourcing of Config.lb files as in the old config tool
|
||||
# as parts are sourced, a device tree is built. The structure
|
||||
# of the tree is determined by the structure of the components
|
||||
# as they are specified. To attach a superio to a southbridge, for
|
||||
# example, one would do this:
|
||||
# southbridge acer/5432
|
||||
# superio nsc/123
|
||||
# end
|
||||
# end
|
||||
# the tool generates static initializers for this hierarchy.
|
||||
|
||||
# add C code to the current component (motherboard, etc. )
|
||||
# to initialise the component-INDEPENDENT structure members
|
||||
init ::= 'init' ``CODE''
|
||||
|
||||
# add C code to the current component (motherboard, etc. )
|
||||
# to initialise the component-DEPENDENT structure members
|
||||
register ::= 'register' ``CODE''
|
||||
|
||||
|
||||
# mainboard command
|
||||
# statements in this block will set variables controlling the mainboard,
|
||||
# and will also place components (northbridge etc.) in the device tree
|
||||
# under this mainboard
|
||||
mainboard ::= 'mainboard' PATH (statements)* 'end'
|
||||
|
||||
# standard linuxbios commands
|
||||
southbridge ::= 'southbridge' PATH (statemnts)* 'end'
|
||||
northbridge ::= 'northbridge' PATH (statemnts)* 'end'
|
||||
superio ::= 'superio PATH (statemnts)* 'end'
|
||||
cpu ::= 'cpu' PATH (statemnts)* 'end'
|
||||
arch ::= 'arch' PATH (statemnts)* 'end'
|
||||
|
||||
# files for building linuxbios
|
||||
# include a file in crt0.S
|
||||
mainboardinit ::= 'mainboardinit' PATH
|
||||
|
||||
# object file
|
||||
object ::= 'object' PATH
|
||||
# driver objects are just built into the image in a different way
|
||||
driver ::= 'driver' PATH
|
||||
|
||||
# Use the Config.lb file in the PATH
|
||||
dir ::= 'dir' PATH
|
||||
|
||||
# add a file to the set of ldscript files
|
||||
ldscript ::= 'ldscript' PATH
|
||||
|
||||
# dependencies or actions for the makerule command
|
||||
dep ::= 'dep' ``dependency-string''
|
||||
act ::= 'act' ``actions''
|
||||
depsacts ::= (dep | act)*
|
||||
# set up a makerule
|
||||
#
|
||||
makerule ::= 'makerule' PATH depsacts
|
||||
|
||||
#defines for use in makefiles only
|
||||
# note usable in the config tool, not passed to cc
|
||||
makedefine ::= 'makedefine' ``RAWTEXT''
|
||||
|
||||
# add an action to an existing make rule
|
||||
addaction ::= 'addaction' PATH ``ACTION''
|
||||
|
||||
# statements
|
||||
statement ::=
|
||||
option
|
||||
| default
|
||||
| cpu
|
||||
| arch
|
||||
| northbridge
|
||||
| southbridge
|
||||
| superio
|
||||
| object
|
||||
| driver
|
||||
| mainboardinit
|
||||
| makerule
|
||||
| makedefine
|
||||
| addaction
|
||||
| init
|
||||
| register
|
||||
| iif
|
||||
| dir
|
||||
| ldscript
|
||||
|
||||
statements ::= (statement)*
|
||||
|
||||
# target directory specification
|
||||
target ::= 'target' PATH
|
||||
|
||||
# and the whole thing
|
||||
board ::= target (option)* mainboard
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
\subsubsection{Command definitions}
|
||||
\subsubsubsection{option}
|
||||
\subsubsubsection{default}
|
||||
\subsubsubsection{cpu}
|
||||
\subsubsubsection{arch}
|
||||
\subsubsubsection{northbridge}
|
||||
\subsubsubsection{southbridge}
|
||||
\subsubsubsection{superio}
|
||||
\subsubsubsection{object}
|
||||
\subsubsubsection{driver}
|
||||
\subsubsubsection{mainboardinit}
|
||||
\subsubsubsection{makerule}
|
||||
\subsubsubsection{makedefine}
|
||||
\subsubsubsection{addaction}
|
||||
\subsubsubsection{init}
|
||||
\subsubsubsection{register}
|
||||
\subsubsubsection{iif}
|
||||
\subsubsubsection{dir}
|
||||
\subsubsubsection{ldscript}
|
||||
|
||||
|
||||
A sample file:
|
||||
|
||||
\begin{verbatim}
|
||||
target x
|
||||
|
||||
# over-ride the default ROM size in the mainboard file
|
||||
option CONFIG_ROM_SIZE=1024*1024
|
||||
mainboard amd/solo
|
||||
end
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
Sample mainboard file
|
||||
\begin{verbatim}
|
||||
#
|
||||
###
|
||||
### Set all of the defaults for an x86 architecture
|
||||
###
|
||||
arch i386 end
|
||||
cpu k8 end
|
||||
#
|
||||
option CONFIG_DEBUG=1
|
||||
default CONFIG_USE_FALLBACK_IMAGE=1
|
||||
option A=(1+2)
|
||||
option B=0xa
|
||||
#
|
||||
###
|
||||
### Build our 16 bit and 32 bit linuxBIOS entry code
|
||||
###
|
||||
mainboardinit cpu/i386/entry16.inc
|
||||
mainboardinit cpu/i386/entry32.inc
|
||||
ldscript cpu/i386/entry16.lds
|
||||
ldscript cpu/i386/entry32.lds
|
||||
#
|
||||
###
|
||||
### Build our reset vector (This is where linuxBIOS is entered)
|
||||
###
|
||||
if CONFIG_USE_FALLBACK_IMAGE
|
||||
mainboardinit cpu/i386/reset16.inc
|
||||
ldscript cpu/i386/reset16.lds
|
||||
else
|
||||
mainboardinit cpu/i386/reset32.inc
|
||||
ldscript cpu/i386/reset32.lds
|
||||
end
|
||||
.
|
||||
.
|
||||
.
|
||||
if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc end
|
||||
#
|
||||
###
|
||||
### Romcc output
|
||||
###
|
||||
#makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
|
||||
#makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
|
||||
#mainboardinit ./failover.inc
|
||||
makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
|
||||
makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
|
||||
mainboardinit ./auto.inc
|
||||
#
|
||||
###
|
||||
### Include the secondary Configuration files
|
||||
###
|
||||
northbridge amd/amdk8
|
||||
end
|
||||
southbridge amd/amd8111
|
||||
end
|
||||
#mainboardinit arch/i386/smp/secondary.inc
|
||||
superio nsc/pc87360
|
||||
register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
|
||||
end
|
||||
dir /pc80
|
||||
##dir /src/superio/winbond/w83627hf
|
||||
cpu p5 end
|
||||
cpu p6 end
|
||||
cpu k7 end
|
||||
cpu k8 end
|
||||
#
|
||||
###
|
||||
### Build the objects we have code for in this directory.
|
||||
###
|
||||
##object mainboard.o
|
||||
driver mainboard.o
|
||||
object static_devices.o
|
||||
if CONFIG_HAVE_MP_TABLE object mptable.o end
|
||||
if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
|
||||
### Location of the DIMM EEPROMS on the SMBUS
|
||||
### This is fixed into a narrow range by the DIMM package standard.
|
||||
###
|
||||
option SMBUS_MEM_DEVICE_START=(0xa << 3)
|
||||
option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
|
||||
option SMBUS_MEM_DEVICE_INC=1
|
||||
#
|
||||
### The linuxBIOS bootloader.
|
||||
###
|
||||
option CONFIG_PAYLOAD_SIZE = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
|
||||
option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
|
||||
#
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
I've found the output of the new tool to be easier to
|
||||
handle. Makefile.settings looks like this, for example:
|
||||
\begin{verbatim}
|
||||
TOP:=/home/rminnich/src/yapps2/freebios2
|
||||
TARGET_DIR:=x
|
||||
export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
|
||||
export CONFIG_ARCH:=i386
|
||||
export CONFIG_RAMBASE:=0x4000
|
||||
export CONFIG_ROM_IMAGE_SIZE:=65535
|
||||
export CONFIG_PAYLOAD_SIZE:=131073
|
||||
export CONFIG_MAX_CPUS:=1
|
||||
export CONFIG_HEAP_SIZE:=8192
|
||||
export CONFIG_STACK_SIZE:=8192
|
||||
export CONFIG_MEMORY_HOLE:=0
|
||||
export COREBOOT_VERSION:=1.1.0
|
||||
export CC:=$(CONFIG_CROSS_COMPILE)gcc
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
In other words, instead of expressions, we see the values. It's easier to
|
||||
deal with.
|
||||
@@ -8,9 +8,8 @@ listed as consumable is subject to change without notice.
|
||||
## Background and Usage
|
||||
|
||||
coreboot passes information to downstream users using coreboot tables. These
|
||||
table definitions can be found in
|
||||
`./src/commonlib/include/commonlib/coreboot_tables.h` and
|
||||
`./payloads/libpayload/include/coreboot_tables.h` respectively within coreboot
|
||||
table definitions can be found in src/include/boot/coreboot_tables.h and
|
||||
payloads/libpayload/include/coreboot_tables.h respectively within coreboot
|
||||
and libpayload. One of the most vital and important pieces of information
|
||||
found within these tables is the memory map of the system indicating
|
||||
available and reserved memory.
|
||||
@@ -1,234 +0,0 @@
|
||||
# Adding new devices to a device tree
|
||||
|
||||
## Introduction
|
||||
|
||||
ACPI exposes a platform-independent interface for operating systems to perform
|
||||
power management and other platform-level functions. Some operating systems
|
||||
also use ACPI to enumerate devices that are not immediately discoverable, such
|
||||
as those behind I2C or SPI busses (in contrast to PCI). This document discusses
|
||||
the way that coreboot uses the concept of a "device tree" to generate ACPI
|
||||
tables for usage by the operating system.
|
||||
|
||||
## Devicetree and overridetree (if applicable)
|
||||
|
||||
For mainboards that are organized around a "reference board" or "baseboard"
|
||||
model (see ``src/mainboard/google/octopus`` or ``hatch`` for examples), there is
|
||||
typically a devicetree.cb file that all boards share, and any differences for a
|
||||
specific board ("variant") are captured in the overridetree.cb file. Any
|
||||
settings changed in the overridetree take precedence over those in the main
|
||||
devicetree. Note, not all mainboards will have the devicetree/overridetree
|
||||
distinction, and may only have a devicetree.cb file. Or you can always just
|
||||
write the ASL (ACPI Source Language) code yourself.
|
||||
|
||||
## Device drivers
|
||||
|
||||
Let's take a look at an example entry from
|
||||
``src/mainboard/google/hatch/variants/hatch/overridetree.cb``:
|
||||
|
||||
```
|
||||
device pci 15.0 on
|
||||
chip drivers/i2c/generic
|
||||
register "hid" = ""ELAN0000""
|
||||
register "desc" = ""ELAN Touchpad""
|
||||
register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
|
||||
register "wake" = "GPE0_DW0_21"
|
||||
device i2c 15 on end
|
||||
end
|
||||
end # I2C #0
|
||||
```
|
||||
|
||||
When this entry is processed during ramstage, it will create a device in the
|
||||
ACPI SSDT table (all devices in devicetrees end up in the SSDT table). The ACPI
|
||||
generation routines in coreboot actually generate the raw bytecode that
|
||||
represents the device's structure, but looking at ASL code is easier to
|
||||
understand; see below for what the disassembled bytecode looks like:
|
||||
|
||||
```
|
||||
Scope (\_SB.PCI0.I2C0)
|
||||
{
|
||||
Device (D015)
|
||||
{
|
||||
Name (_HID, "ELAN0000") // _HID: Hardware ID
|
||||
Name (_UID, Zero) // _UID: Unique ID
|
||||
Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
|
||||
Method (_STA, 0, NotSerialized) // _STA: Status
|
||||
{
|
||||
Return (0x0F)
|
||||
}
|
||||
Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings
|
||||
{
|
||||
I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
|
||||
AddressingMode7Bit, "\\_SB.PCI0.I2C0",
|
||||
0x00, ResourceConsumer, , Exclusive, )
|
||||
Interrupt (ResourceConsumer, Edge, ActiveLow, ExclusiveAndWake, ,, )
|
||||
{
|
||||
0x0000002D,
|
||||
}
|
||||
})
|
||||
Name (_S0W, 0x04) // _S0W: S0 Device Wake State
|
||||
Name (_PRW, Package (0x02) // _PRW: Power Resources for Wake
|
||||
{
|
||||
0x15, // GPE #21
|
||||
0x03 // Sleep state S3
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can see it generates _HID, _UID, _DDN, _STA, _CRS, _S0W, and _PRW
|
||||
names/methods in the Device's scope.
|
||||
|
||||
## Utilizing a device driver
|
||||
|
||||
The device driver must be enabled for your build. There will be a CONFIG option
|
||||
in the Kconfig file in the directory that the driver is in (e.g.,
|
||||
``src/drivers/i2c/generic`` contains a Kconfig file; the option here is named
|
||||
CONFIG_DRIVERS_I2C_GENERIC). The config option will need to be added to your
|
||||
mainboard's Kconfig file (e.g., ``src/mainboard/google/hatch/Kconfig``) in order
|
||||
to be compiled into your build.
|
||||
|
||||
## Diving into the above example:
|
||||
|
||||
Let's take a look at how the devicetree language corresponds to the generated
|
||||
ASL.
|
||||
|
||||
First, note this:
|
||||
|
||||
```
|
||||
chip drivers/i2c/generic
|
||||
```
|
||||
|
||||
This means that the device driver we're using has a corresponding structure,
|
||||
located at ``src/drivers/i2c/generic/chip.h``, named **struct
|
||||
drivers_i2c_generic_config** and it contains many properties you can specify to
|
||||
be included in the ACPI table.
|
||||
|
||||
### hid
|
||||
|
||||
```
|
||||
register "hid" = ""ELAN0000""
|
||||
```
|
||||
|
||||
This corresponds to **const char *hid** in the struct. In the ACPI ASL, it
|
||||
translates to:
|
||||
|
||||
```
|
||||
Name (_HID, "ELAN0000") // _HID: Hardware ID
|
||||
```
|
||||
|
||||
under the device. **This property is used to match the device to its driver
|
||||
during enumeration in the OS.**
|
||||
|
||||
### desc
|
||||
|
||||
```
|
||||
register "desc" = ""ELAN Touchpad""
|
||||
```
|
||||
|
||||
corresponds to **const char *desc** and in ASL:
|
||||
|
||||
```
|
||||
Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
|
||||
```
|
||||
|
||||
### irq
|
||||
|
||||
It also adds the interrupt,
|
||||
|
||||
```
|
||||
Interrupt (ResourceConsumer, Edge, ActiveLow, ExclusiveAndWake, ,, )
|
||||
{
|
||||
0x0000002D,
|
||||
}
|
||||
```
|
||||
|
||||
which comes from:
|
||||
|
||||
```
|
||||
register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
|
||||
```
|
||||
|
||||
The GPIO pin IRQ settings control the "Edge", "ActiveLow", and
|
||||
"ExclusiveAndWake" settings seen above (edge means it is an edge-triggered
|
||||
interrupt as opposed to level-triggered; active low means the interrupt is
|
||||
triggered on a falling edge).
|
||||
|
||||
Note that the ACPI_IRQ_WAKE_EDGE_LOW macro informs the platform that the GPIO
|
||||
will be routed through SCI (ACPI's System Control Interrupt) for use as a wake
|
||||
source. Also note that the IRQ names are SoC-specific, and you will need to
|
||||
find the names in your SoC's header file. The ACPI_* macros are defined in
|
||||
``src/arch/x86/include/acpi/acpi_device.h``.
|
||||
|
||||
Using a GPIO as an IRQ requires that it is configured in coreboot correctly.
|
||||
This is often done in a mainboard-specific file named ``gpio.c``.
|
||||
|
||||
### wake
|
||||
|
||||
The last register is:
|
||||
|
||||
```
|
||||
register "wake" = "GPE0_DW0_21"
|
||||
```
|
||||
|
||||
which indicates that the method of waking the system using the touchpad will be
|
||||
through a GPE, #21 associated with DW0, which is set up in devicetree.cb from
|
||||
this example. The "21" indicates GPP_X21, where GPP_X is mapped onto DW0
|
||||
elsewhere in the devicetree.
|
||||
|
||||
The last bit of the definition of that device includes:
|
||||
|
||||
```
|
||||
device i2c 15 on end
|
||||
```
|
||||
|
||||
which means it's an I2C device, with 7-bit address 0x15, and the device is "on",
|
||||
meaning it will be exposed in the ACPI table. The PCI device that the
|
||||
controller is located in determines which I2C bus the device is expected to be
|
||||
found on. In this example, this is I2C bus 0. This also determines the ACPI
|
||||
"Scope" that the device names and methods will live under, in this case
|
||||
"\_SB.PCI0.I2C0".
|
||||
|
||||
## Other auto-generated names
|
||||
|
||||
(see [ACPI specification
|
||||
6.3](https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf)
|
||||
for more details on ACPI methods)
|
||||
|
||||
### _S0W (S0 Device Wake State)
|
||||
_S0W indicates the deepest S0 sleep state this device can wake itself from,
|
||||
which in this case is 4, representing _D3cold_.
|
||||
|
||||
### _PRW (Power Resources for Wake)
|
||||
_PRW indicates the power resources and events required for wake. There are no
|
||||
dependent power resources, but the GPE (GPE0_DW0_21) is mentioned here (0x15),
|
||||
as well as the deepest sleep state supporting waking the system (3), which is
|
||||
S3.
|
||||
|
||||
### _STA (Status)
|
||||
The _STA method is generated automatically, and its values, 0xF, indicates the
|
||||
following:
|
||||
|
||||
Bit [0] – Set if the device is present.
|
||||
Bit [1] – Set if the device is enabled and decoding its resources.
|
||||
Bit [2] – Set if the device should be shown in the UI.
|
||||
Bit [3] – Set if the device is functioning properly (cleared if device failed its diagnostics).
|
||||
|
||||
### _CRS (Current resource settings)
|
||||
The _CRS method is generated automatically, as the driver knows it is an I2C
|
||||
controller, and so specifies how to configure the controller for proper
|
||||
operation with the touchpad.
|
||||
|
||||
```
|
||||
Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings
|
||||
{
|
||||
I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
|
||||
AddressingMode7Bit, "\\_SB.PCI0.I2C0",
|
||||
0x00, ResourceConsumer, , Exclusive, )
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **All fields that are left unspecified in the devicetree are initialized to
|
||||
zero.**
|
||||
- **All devices in devicetrees end up in the SSDT table, and are generated in
|
||||
coreboot's ramstage**
|
||||
@@ -73,15 +73,6 @@ calling the platform specific acpigen_soc_{set,clear}_tx_gpio
|
||||
functions internally. Thus, all the ACPI AML calling conventions for
|
||||
the platform functions apply to these helper functions as well.
|
||||
|
||||
3. Get Rx GPIO
|
||||
int acpigen_get_rx_gpio(struct acpi_gpio gpio)
|
||||
|
||||
This function takes as input, an struct acpi_gpio type and outputs
|
||||
AML code to read the *logical* value of a gpio (after taking its
|
||||
polarity into consideration), into the Local0 variable. It calls
|
||||
the platform specific acpigen_soc_read_rx_gpio() to actually read
|
||||
the raw Rx gpio value.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
ACPI library in coreboot will provide weak definitions for all the
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
# ACPI-specific documentation
|
||||
|
||||
This section contains documentation about coreboot on ACPI. coreboot dropped
|
||||
backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
|
||||
upwards.
|
||||
|
||||
|
||||
- [SSDT UID generation](uid.md)
|
||||
|
||||
## GPIO
|
||||
|
||||
- [GPIO toggling in ACPI AML](gpio.md)
|
||||
|
||||
## devicetree
|
||||
|
||||
- [Adding devices to a device tree](devicetree.md)
|
||||
@@ -1,14 +0,0 @@
|
||||
# ACPI SSDT \_UID generation
|
||||
|
||||
According to the ACPI spec:
|
||||
|
||||
> The _UID must be unique across all devices with either a common _HID or _CID.
|
||||
|
||||
|
||||
When generating SSDTs in coreboot the independent drivers don't know
|
||||
which \_UID is already in use for a specific \_HID or \_CID. To generate
|
||||
unique \_UIDs the ACPI device's path is hashed and used as ID. As every ACPI
|
||||
device has a different path, the hash will be also different for every device.
|
||||
|
||||
Windows 10 verifies all devices with the same \_HID or \_CID and makes
|
||||
sure that no \_UID is duplicated. If it is it'll BSOD.
|
||||
@@ -1,11 +0,0 @@
|
||||
# Architecture-specific documentation
|
||||
|
||||
This section contains documentation about coreboot on specific CPU
|
||||
architectures.
|
||||
|
||||
## RISC-V
|
||||
|
||||
- [RISC-V documentation](riscv/index.md)
|
||||
|
||||
## x86
|
||||
- [x86 documentation](x86/index.md)
|
||||
@@ -1,64 +0,0 @@
|
||||
# RISC-V architecture documentation
|
||||
|
||||
This section contains documentation about coreboot on RISC-V architecture.
|
||||
|
||||
## Mode usage
|
||||
All stages run in M mode.
|
||||
|
||||
Payloads have a choice of managing M mode activity: they can control
|
||||
everything or nothing.
|
||||
|
||||
Payloads run from the romstage (i.e. rampayloads) are started in M mode.
|
||||
The payload must, for example, prepare and install its own SBI.
|
||||
|
||||
Payloads run from the ramstage are started in S mode, and trap delegation
|
||||
will have been done. These payloads rely on the SBI and can not replace it.
|
||||
|
||||
## Stage handoff protocol
|
||||
On entry to a stage or payload (including SELF payloads),
|
||||
* all harts are running.
|
||||
* A0 is the hart ID.
|
||||
* A1 is the pointer to the Flattened Device Tree (FDT).
|
||||
* A2 contains the additional program calling argument:
|
||||
- cbmem_top for ramstage
|
||||
- the address of the payload for opensbi
|
||||
|
||||
## Additional payload handoff requirements
|
||||
The location of cbmem should be placed in a node in the FDT.
|
||||
|
||||
## OpenSBI
|
||||
In case the payload doesn't install it's own SBI, like the [RISCV-PK] does,
|
||||
[OpenSBI] can be used instead.
|
||||
It's loaded into RAM after coreboot has finished loading the payload.
|
||||
coreboot then will jump to OpenSBI providing a pointer to the real payload,
|
||||
which OpenSBI will jump to once the SBI is installed.
|
||||
|
||||
Besides providing SBI it also sets protected memory regions and provides
|
||||
a platform independent console.
|
||||
|
||||
The OpenSBI code is always run in M mode.
|
||||
|
||||
## Trap delegation
|
||||
Traps are delegated to the payload.
|
||||
|
||||
## SMP within a stage
|
||||
At the beginning of each stage, all harts save 0 are spinning in a loop on
|
||||
a semaphore. At the end of the stage harts 1..max are released by changing
|
||||
the semaphore.
|
||||
|
||||
A possible way to do this is to have a pointer to a struct containing
|
||||
variables, e.g.
|
||||
|
||||
```c
|
||||
struct blocker {
|
||||
void (*fn)(); // never returns
|
||||
}
|
||||
```
|
||||
|
||||
The hart blocks until fn is non-null, and then calls it. If fn returns, we
|
||||
will panic if possible, but behavior is largely undefined.
|
||||
|
||||
Only hart 0 runs through most of the code in each stage.
|
||||
|
||||
[RISCV-PK]: https://github.com/riscv/riscv-pk
|
||||
[OpenSBI]: https://github.com/riscv/opensbi
|
||||
@@ -1,67 +0,0 @@
|
||||
# x86 architecture documentation
|
||||
|
||||
This section contains documentation about coreboot on x86 architecture.
|
||||
|
||||
* [x86 PAE support](pae.md)
|
||||
|
||||
## State of x86_64 support
|
||||
At the moment there's only experimental x86_64 support.
|
||||
The `emulation/qemu-i440fx` and `emulation/qemu-q35` boards do support
|
||||
*ARCH_RAMSTAGE_X86_64* , *ARCH_POSTCAR_X86_64* and *ARCH_ROMSTAGE_X86_64*.
|
||||
|
||||
In order to add support for x86_64 the following assumptions were made:
|
||||
* The CPU supports long mode
|
||||
* All memory returned by malloc must be below 4GiB in physical memory
|
||||
* All code that is to be run must be below 4GiB in physical memory
|
||||
* The high dword of pointers is always zero
|
||||
* The reference implementation is qemu
|
||||
* The CPU supports 1GiB hugepages
|
||||
* x86 payloads are loaded below 4GiB in physical memory and are jumped
|
||||
to in *protected mode*
|
||||
|
||||
## Assumptions for all stages using the reference implementation
|
||||
* 0-4GiB are identity mapped using 2MiB-pages as WB
|
||||
* Memory above 4GiB isn't accessible
|
||||
* page tables reside in memory mapped ROM
|
||||
* A stage can install new page tables in RAM
|
||||
|
||||
## Page tables
|
||||
Page tables are generated by a tool in `util/pgtblgen/pgtblgen`. It writes
|
||||
the page tables to a file which is then included into the CBFS as file called
|
||||
`pagetables`.
|
||||
|
||||
To generate the static page tables it must know the physical address where to
|
||||
place the file.
|
||||
|
||||
The page tables contains the following structure:
|
||||
* PML4E pointing to PDPE
|
||||
* PDPE with *$n* entries each pointing to PDE
|
||||
* *$n* PDEs with 512 entries each
|
||||
|
||||
At the moment *$n* is 4, which results in identity mapping the lower 4 GiB.
|
||||
|
||||
## Basic x86_64 support
|
||||
Basic support for x86_64 has been implemented for QEMU mainboard target.
|
||||
|
||||
## Reference implementation
|
||||
The reference implementation is
|
||||
* [QEMU i440fx](../../mainboard/emulation/qemu-i440fx.md)
|
||||
* [QEMU Q35](../../mainboard/emulation/qemu-q35.md)
|
||||
|
||||
## TODO
|
||||
* Identity map memory above 4GiB in ramstage
|
||||
|
||||
## Future work
|
||||
|
||||
1. Fine grained page tables for SMM:
|
||||
* Must not have execute and write permissions for the same page.
|
||||
* Must allow only that TSEG pages can be marked executable
|
||||
* Must reside in SMRAM
|
||||
2. Support 64bit PCI BARs above 4GiB
|
||||
3. Place and run code above 4GiB
|
||||
|
||||
## Porting other boards
|
||||
* Fix compilation errors
|
||||
* Test how well CAR works with x86_64 and paging
|
||||
* Improve mode switches
|
||||
* Test libgfxinit / VGA Option ROMs / FSP
|
||||
@@ -1,15 +0,0 @@
|
||||
# x86_32 PAE documentation
|
||||
|
||||
Due to missing x86_64 support it's required to use PAE enabled x86_32 code.
|
||||
The corresponding functions can be found in ``src/cpu/x86/pae/``.
|
||||
|
||||
## Memory clearing helper functions
|
||||
|
||||
To clear all DRAM on request of the
|
||||
[Security API](../../security/memory_clearing.md), a helper function can be used
|
||||
called `memset_pae`.
|
||||
The function has additional requirements in contrast to `memset`, and has more
|
||||
overhead as it uses virtual memory to access memory above 4GiB.
|
||||
Memory is cleared in 2MiB chunks, which might take a while.
|
||||
|
||||
Make sure to enable caches through MTRRs, otherwise `memset_pae` will be slow!
|
||||
@@ -174,7 +174,7 @@ with
|
||||
regards to the erase block sizes on the ROM - allowing one to replace a
|
||||
component at runtime without disturbing the others.
|
||||
|
||||
'offset' is the offset of the first CBFS component (from the start of
|
||||
'offset' is the offset of the the first CBFS component (from the start of
|
||||
the ROM). This is to allow for arbitrary space to be left at the beginning
|
||||
of the ROM for things like embedded controller firmware.
|
||||
|
||||
@@ -384,7 +384,7 @@ PAYLOAD_SEGMENT_BSS 0x20535342 The memory specified by the segment
|
||||
PAYLOAD_SEGMENT_PARAMS 0x41524150 The segment contains information for
|
||||
the payload
|
||||
PAYLOAD_SEGMENT_ENTRY 0x52544E45 The segment contains the entry point
|
||||
for the payload
|
||||
for the payload
|
||||
|
||||
'compression' is the compression scheme for the segment. Each segment can
|
||||
be independently compressed. There are three compression types defined by
|
||||
|
||||
@@ -98,10 +98,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7
|
||||
132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439 "/>
|
||||
132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181 "/>
|
||||
<polygon fill="#231F20" points="131.152,57.643 132.28,59.108 118.41,57.093 117.644,56.096 "/>
|
||||
<polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181 "/>
|
||||
<polygon fill="#231F20" points="131.152,57.643 132.28,59.108 118.41,57.093 117.644,56.096 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -118,10 +118,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7
|
||||
132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439 "/>
|
||||
132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181 "/>
|
||||
<polygon fill="#231F20" points="131.152,107.643 132.28,109.108 118.41,107.093 117.644,106.096 "/>
|
||||
<polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181 "/>
|
||||
<polygon fill="#231F20" points="131.152,107.643 132.28,109.108 118.41,107.093 117.644,106.096 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -138,10 +138,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041
|
||||
132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78 "/>
|
||||
132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522 "/>
|
||||
<polygon fill="#231F20" points="131.152,177.983 132.28,179.449 118.41,177.434 117.644,176.437 "/>
|
||||
<polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522 "/>
|
||||
<polygon fill="#231F20" points="131.152,177.983 132.28,179.449 118.41,177.434 117.644,176.437 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -158,10 +158,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467
|
||||
132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207 "/>
|
||||
132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948 "/>
|
||||
<polygon fill="#231F20" points="131.152,253.41 132.28,254.875 118.41,252.86 117.644,251.863 "/>
|
||||
<polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948 "/>
|
||||
<polygon fill="#231F20" points="131.152,253.41 132.28,254.875 118.41,252.86 117.644,251.863 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -178,10 +178,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468
|
||||
132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207 "/>
|
||||
132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948 "/>
|
||||
<polygon fill="#231F20" points="131.152,329.41 132.28,330.876 118.41,328.86 117.643,327.864 "/>
|
||||
<polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948 "/>
|
||||
<polygon fill="#231F20" points="131.152,329.41 132.28,330.876 118.41,328.86 117.643,327.864 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -198,10 +198,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327
|
||||
132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066 "/>
|
||||
132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808 "/>
|
||||
<polygon fill="#231F20" points="131.152,422.27 132.28,423.735 118.41,421.72 117.644,420.724 "/>
|
||||
<polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808 "/>
|
||||
<polygon fill="#231F20" points="131.152,422.27 132.28,423.735 118.41,421.72 117.644,420.724 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
@@ -218,10 +218,10 @@
|
||||
<g>
|
||||
<g>
|
||||
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608
|
||||
132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347 "/>
|
||||
132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347 "/>
|
||||
</g>
|
||||
<polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089 "/>
|
||||
<polygon fill="#231F20" points="131.152,478.551 132.28,480.017 118.41,478.001 117.643,477.004 "/>
|
||||
<polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089 "/>
|
||||
<polygon fill="#231F20" points="131.152,478.551 132.28,480.017 118.41,478.001 117.643,477.004 "/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
|
||||
|
Before Width: | Height: | Size: 17 KiB After Width: | Height: | Size: 17 KiB |
@@ -1,938 +0,0 @@
|
||||
# Coding Style
|
||||
|
||||
This is a short document describing the preferred coding style for the
|
||||
coreboot project. It is in many ways exactly the same as the Linux
|
||||
kernel coding style. In fact, most of this document has been copied from
|
||||
the [Linux kernel coding style](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/CodingStyle?id=HEAD)
|
||||
|
||||
Please at least consider the points made here.
|
||||
|
||||
First off, I'd suggest printing out a copy of the GNU coding standards,
|
||||
and NOT read it. Burn them, it's a great symbolic gesture.
|
||||
|
||||
Anyway, here goes:
|
||||
|
||||
## Indentation
|
||||
|
||||
Tabs are 8 characters, and thus indentations are also 8 characters.
|
||||
There are heretic movements that try to make indentations 4 (or even 2!)
|
||||
characters deep, and that is akin to trying to define the value of PI to
|
||||
be 3.
|
||||
|
||||
Rationale: The whole idea behind indentation is to clearly define where
|
||||
a block of control starts and ends. Especially when you've been looking
|
||||
at your screen for 20 straight hours, you'll find it a lot easier to
|
||||
see how the indentation works if you have large indentations.
|
||||
|
||||
Now, some people will claim that having 8-character indentations makes
|
||||
the code move too far to the right, and makes it hard to read on a
|
||||
80-character terminal screen. The answer to that is that if you need
|
||||
more than 3 levels of indentation, you're screwed anyway, and should
|
||||
fix your program.
|
||||
|
||||
In short, 8-char indents make things easier to read, and have the added
|
||||
benefit of warning you when you're nesting your functions too deep.
|
||||
Heed that warning.
|
||||
|
||||
The preferred way to ease multiple indentation levels in a switch
|
||||
statement is to align the "switch" and its subordinate "case" labels
|
||||
in the same column instead of "double-indenting" the "case" labels.
|
||||
E.g.:
|
||||
|
||||
```c
|
||||
switch (suffix) {
|
||||
case 'G':
|
||||
case 'g':
|
||||
mem <<= 30;
|
||||
break;
|
||||
case 'M':
|
||||
case 'm':
|
||||
mem <<= 20;
|
||||
break;
|
||||
case 'K':
|
||||
case 'k':
|
||||
mem <<= 10;
|
||||
/* fall through */
|
||||
default:
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
Don't put multiple statements on a single line unless you have
|
||||
something to hide:
|
||||
|
||||
```c
|
||||
if (condition) do_this;
|
||||
do_something_everytime;
|
||||
```
|
||||
|
||||
Don't put multiple assignments on a single line either. Kernel coding
|
||||
style is super simple. Avoid tricky expressions.
|
||||
|
||||
Outside of comments, documentation and except in Kconfig, spaces are
|
||||
never used for indentation, and the above example is deliberately
|
||||
broken.
|
||||
|
||||
Get a decent editor and don't leave whitespace at the end of lines.
|
||||
|
||||
## Breaking long lines and strings
|
||||
|
||||
Coding style is all about readability and maintainability using commonly
|
||||
available tools.
|
||||
|
||||
The limit on the length of lines is 96 columns and this is a strongly
|
||||
preferred limit.
|
||||
|
||||
Statements longer than 96 columns will be broken into sensible chunks,
|
||||
unless exceeding 96 columns significantly increases readability and does
|
||||
not hide information. Descendants are always substantially shorter than
|
||||
the parent and are placed substantially to the right. The same applies
|
||||
to function headers with a long argument list. However, never break
|
||||
user-visible strings such as printk messages, because that breaks the
|
||||
ability to grep for them.
|
||||
|
||||
## Placing Braces and Spaces
|
||||
|
||||
The other issue that always comes up in C styling is the placement of
|
||||
braces. Unlike the indent size, there are few technical reasons to
|
||||
choose one placement strategy over the other, but the preferred way, as
|
||||
shown to us by the prophets Kernighan and Ritchie, is to put the opening
|
||||
brace last on the line, and put the closing brace first, thusly:
|
||||
|
||||
```c
|
||||
if (x is true) {
|
||||
we do y
|
||||
}
|
||||
```
|
||||
|
||||
This applies to all non-function statement blocks (if, switch, for,
|
||||
while, do). E.g.:
|
||||
|
||||
```c
|
||||
switch (action) {
|
||||
case KOBJ_ADD:
|
||||
return "add";
|
||||
case KOBJ_REMOVE:
|
||||
return "remove";
|
||||
case KOBJ_CHANGE:
|
||||
return "change";
|
||||
default:
|
||||
return NULL;
|
||||
}
|
||||
```
|
||||
|
||||
However, there is one special case, namely functions: they have the
|
||||
opening brace at the beginning of the next line, thus:
|
||||
|
||||
```c
|
||||
int function(int x)
|
||||
{
|
||||
body of function
|
||||
}
|
||||
```
|
||||
|
||||
Heretic people all over the world have claimed that this inconsistency
|
||||
is ... well ... inconsistent, but all right-thinking people know that
|
||||
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
|
||||
special anyway (you can't nest them in C).
|
||||
|
||||
Note that the closing brace is empty on a line of its own, _except_ in
|
||||
the cases where it is followed by a continuation of the same statement,
|
||||
ie a "while" in a do-statement or an "else" in an if-statement, like
|
||||
this:
|
||||
|
||||
```c
|
||||
do {
|
||||
body of do-loop
|
||||
} while (condition);
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```c
|
||||
if (x == y) {
|
||||
..
|
||||
} else if (x > y) {
|
||||
...
|
||||
} else {
|
||||
....
|
||||
}
|
||||
```
|
||||
|
||||
Rationale: K&R.
|
||||
|
||||
Also, note that this brace-placement also minimizes the number of empty
|
||||
(or almost empty) lines, without any loss of readability. Thus, as the
|
||||
supply of new-lines on your screen is not a renewable resource (think
|
||||
25-line terminal screens here), you have more empty lines to put
|
||||
comments on.
|
||||
|
||||
Do not unnecessarily use braces where a single statement will do.
|
||||
|
||||
```c
|
||||
if (condition)
|
||||
action();
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```c
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
```
|
||||
|
||||
This does not apply if only one branch of a conditional statement is a
|
||||
single statement; in the latter case use braces in both branches:
|
||||
|
||||
```c
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
```
|
||||
|
||||
### Spaces
|
||||
|
||||
Linux kernel style for use of spaces depends (mostly) on
|
||||
function-versus-keyword usage. Use a space after (most) keywords. The
|
||||
notable exceptions are sizeof, typeof, alignof, and __attribute__,
|
||||
which look somewhat like functions (and are usually used with
|
||||
parentheses in Linux, although they are not required in the language, as
|
||||
in: "sizeof info" after "struct fileinfo info;" is declared).
|
||||
|
||||
So use a space after these keywords:
|
||||
|
||||
```
|
||||
if, switch, case, for, do, while
|
||||
```
|
||||
|
||||
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||
|
||||
```c
|
||||
s = sizeof(struct file);
|
||||
```
|
||||
|
||||
Do not add spaces around (inside) parenthesized expressions. This
|
||||
example is
|
||||
|
||||
- bad*:
|
||||
|
||||
```c
|
||||
s = sizeof( struct file );
|
||||
```
|
||||
|
||||
When declaring pointer data or a function that returns a pointer type,
|
||||
the preferred use of '*' is adjacent to the data name or function
|
||||
name and not adjacent to the type name. Examples:
|
||||
|
||||
```c
|
||||
char *linux_banner;
|
||||
unsigned long long memparse(char *ptr, char **retptr);
|
||||
char *match_strdup(substring_t *s);
|
||||
```
|
||||
|
||||
Use one space around (on each side of) most binary and ternary
|
||||
operators, such as any of these:
|
||||
|
||||
```
|
||||
= + - < > * / % | & ^ <= >= == != ? :
|
||||
```
|
||||
|
||||
but no space after unary operators:
|
||||
|
||||
```
|
||||
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||
```
|
||||
|
||||
no space before the postfix increment & decrement unary operators:
|
||||
|
||||
```
|
||||
++ --
|
||||
```
|
||||
|
||||
no space after the prefix increment & decrement unary operators:
|
||||
|
||||
```
|
||||
++ --
|
||||
```
|
||||
|
||||
and no space around the '.' and "->" structure member operators.
|
||||
|
||||
Do not leave trailing whitespace at the ends of lines. Some editors with
|
||||
"smart" indentation will insert whitespace at the beginning of new
|
||||
lines as appropriate, so you can start typing the next line of code
|
||||
right away. However, some such editors do not remove the whitespace if
|
||||
you end up not putting a line of code there, such as if you leave a
|
||||
blank line. As a result, you end up with lines containing trailing
|
||||
whitespace.
|
||||
|
||||
Git will warn you about patches that introduce trailing whitespace, and
|
||||
can optionally strip the trailing whitespace for you; however, if
|
||||
applying a series of patches, this may make later patches in the series
|
||||
fail by changing their context lines.
|
||||
|
||||
### Naming
|
||||
|
||||
C is a Spartan language, and so should your naming be. Unlike Modula-2
|
||||
and Pascal programmers, C programmers do not use cute names like
|
||||
ThisVariableIsATemporaryCounter. A C programmer would call that variable
|
||||
"tmp", which is much easier to write, and not the least more difficult
|
||||
to understand.
|
||||
|
||||
HOWEVER, while mixed-case names are frowned upon, descriptive names for
|
||||
global variables are a must. To call a global function "foo" is a
|
||||
shooting offense.
|
||||
|
||||
GLOBAL variables (to be used only if you _really_ need them) need to
|
||||
have descriptive names, as do global functions. If you have a function
|
||||
that counts the number of active users, you should call that
|
||||
"count_active_users()" or similar, you should _not_ call it
|
||||
"cntusr()".
|
||||
|
||||
Encoding the type of a function into the name (so-called Hungarian
|
||||
notation) is brain damaged - the compiler knows the types anyway and can
|
||||
check those, and it only confuses the programmer. No wonder MicroSoft
|
||||
makes buggy programs.
|
||||
|
||||
LOCAL variable names should be short, and to the point. If you have some
|
||||
random integer loop counter, it should probably be called "i". Calling
|
||||
it "loop_counter" is non-productive, if there is no chance of it
|
||||
being mis-understood. Similarly, "tmp" can be just about any type of
|
||||
variable that is used to hold a temporary value.
|
||||
|
||||
If you are afraid to mix up your local variable names, you have another
|
||||
problem, which is called the function-growth-hormone-imbalance syndrome.
|
||||
See chapter 6 (Functions).
|
||||
|
||||
## Typedefs
|
||||
|
||||
Please don't use things like "vps_t".
|
||||
|
||||
It's a _mistake_ to use typedef for structures and pointers. When you
|
||||
see a
|
||||
|
||||
```c
|
||||
vps_t a;
|
||||
```
|
||||
|
||||
in the source, what does it mean?
|
||||
|
||||
In contrast, if it says
|
||||
|
||||
```c
|
||||
struct virtual_container *a;
|
||||
```
|
||||
|
||||
you can actually tell what "a" is.
|
||||
|
||||
Lots of people think that typedefs "help readability". Not so. They
|
||||
are useful only for:
|
||||
|
||||
(a) totally opaque objects (where the typedef is actively used to
|
||||
_hide_ what the object is).
|
||||
|
||||
Example: "pte_t" etc. opaque objects that you can only access using
|
||||
the proper accessor functions.
|
||||
|
||||
NOTE! Opaqueness and "accessor functions" are not good in themselves.
|
||||
The reason we have them for things like pte_t etc. is that there really
|
||||
is absolutely _zero_ portably accessible information there.
|
||||
|
||||
(b) Clear integer types, where the abstraction _helps_ avoid confusion
|
||||
whether it is "int" or "long".
|
||||
|
||||
u8/u16/u32 are perfectly fine typedefs, although they fit into category
|
||||
(d) better than here.
|
||||
|
||||
NOTE! Again - there needs to be a _reason_ for this. If something is
|
||||
"unsigned long", then there's no reason to do
|
||||
|
||||
```c
|
||||
typedef unsigned long myflags_t;
|
||||
```
|
||||
|
||||
but if there is a clear reason for why it under certain circumstances
|
||||
might be an "unsigned int" and under other configurations might be
|
||||
"unsigned long", then by all means go ahead and use a typedef.
|
||||
|
||||
(c) when you use sparse to literally create a _new_ type for
|
||||
type-checking.
|
||||
|
||||
(d) New types which are identical to standard C99 types, in certain
|
||||
exceptional circumstances.
|
||||
|
||||
Although it would only take a short amount of time for the eyes and
|
||||
brain to become accustomed to the standard types like 'uint32_t',
|
||||
some people object to their use anyway.
|
||||
|
||||
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their signed
|
||||
equivalents which are identical to standard types are permitted --
|
||||
although they are not mandatory in new code of your own.
|
||||
|
||||
When editing existing code which already uses one or the other set of
|
||||
types, you should conform to the existing choices in that code.
|
||||
|
||||
(e) Types safe for use in userspace.
|
||||
|
||||
In certain structures which are visible to userspace, we cannot require
|
||||
C99 types and cannot use the 'u32' form above. Thus, we use __u32
|
||||
and similar types in all structures which are shared with userspace.
|
||||
|
||||
Maybe there are other cases too, but the rule should basically be to
|
||||
NEVER EVER use a typedef unless you can clearly match one of those
|
||||
rules.
|
||||
|
||||
In general, a pointer, or a struct that has elements that can reasonably
|
||||
be directly accessed should _never_ be a typedef.
|
||||
|
||||
## Functions
|
||||
|
||||
Functions should be short and sweet, and do just one thing. They should
|
||||
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
|
||||
as we all know), and do one thing and do that well.
|
||||
|
||||
The maximum length of a function is inversely proportional to the
|
||||
complexity and indentation level of that function. So, if you have a
|
||||
conceptually simple function that is just one long (but simple)
|
||||
case-statement, where you have to do lots of small things for a lot of
|
||||
different cases, it's OK to have a longer function.
|
||||
|
||||
However, if you have a complex function, and you suspect that a
|
||||
less-than-gifted first-year high-school student might not even
|
||||
understand what the function is all about, you should adhere to the
|
||||
maximum limits all the more closely. Use helper functions with
|
||||
descriptive names (you can ask the compiler to in-line them if you think
|
||||
it's performance-critical, and it will probably do a better job of it
|
||||
than you would have done).
|
||||
|
||||
Another measure of the function is the number of local variables. They
|
||||
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
|
||||
function, and split it into smaller pieces. A human brain can generally
|
||||
easily keep track of about 7 different things, anything more and it gets
|
||||
confused. You know you're brilliant, but maybe you'd like to
|
||||
understand what you did 2 weeks from now.
|
||||
|
||||
In source files, separate functions with one blank line. If the function
|
||||
is exported, the EXPORT* macro for it should follow immediately after
|
||||
the closing function brace line. E.g.:
|
||||
|
||||
```c
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
```
|
||||
|
||||
In function prototypes, include parameter names with their data types.
|
||||
Although this is not required by the C language, it is preferred in
|
||||
Linux because it is a simple way to add valuable information for the
|
||||
reader.
|
||||
|
||||
## Centralized exiting of functions
|
||||
|
||||
Albeit deprecated by some people, the equivalent of the goto statement
|
||||
is used frequently by compilers in form of the unconditional jump
|
||||
instruction.
|
||||
|
||||
The goto statement comes in handy when a function exits from multiple
|
||||
locations and some common work such as cleanup has to be done. If there
|
||||
is no cleanup needed then just return directly.
|
||||
|
||||
The rationale is:
|
||||
|
||||
- unconditional statements are easier to understand and follow
|
||||
- nesting is reduced
|
||||
- errors by not updating individual exit points when making
|
||||
modifications are prevented
|
||||
- saves the compiler work to optimize redundant code away ;)
|
||||
|
||||
```c
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer = kmalloc(SIZE);
|
||||
|
||||
if (buffer == NULL)
|
||||
return -ENOMEM;
|
||||
|
||||
if (condition1) {
|
||||
while (loop1) {
|
||||
...
|
||||
}
|
||||
result = 1;
|
||||
goto out;
|
||||
}
|
||||
...
|
||||
out:
|
||||
kfree(buffer);
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
## Commenting
|
||||
|
||||
Comments are good, but there is also a danger of over-commenting. NEVER
|
||||
try to explain HOW your code works in a comment: it's much better to
|
||||
write the code so that the _working_ is obvious, and it's a waste of
|
||||
time to explain badly written code.
|
||||
|
||||
Generally, you want your comments to tell WHAT your code does, not HOW.
|
||||
Also, try to avoid putting comments inside a function body: if the
|
||||
function is so complex that you need to separately comment parts of it,
|
||||
you should probably go back to chapter 6 for a while. You can make small
|
||||
comments to note or warn about something particularly clever (or ugly),
|
||||
but try to avoid excess. Instead, put the comments at the head of the
|
||||
function, telling people what it does, and possibly WHY it does it.
|
||||
|
||||
When commenting the kernel API functions, please use the kernel-doc
|
||||
format. See the files Documentation/kernel-doc-nano-HOWTO.txt and
|
||||
scripts/kernel-doc for details.
|
||||
|
||||
coreboot style for comments is the C89 "/* ... */" style. You may
|
||||
use C99-style "// ..." comments.
|
||||
|
||||
The preferred style for *short* (multi-line) comments is:
|
||||
|
||||
```c
|
||||
/* This is the preferred style for short multi-line
|
||||
comments in the Linux kernel source code.
|
||||
Please use it consistently. */
|
||||
```
|
||||
|
||||
The preferred style for *long* (multi-line) comments is:
|
||||
|
||||
```c
|
||||
/*
|
||||
* This is the preferred style for multi-line
|
||||
* comments in the Linux kernel source code.
|
||||
* Please use it consistently.
|
||||
*
|
||||
* Description: A column of asterisks on the left side,
|
||||
* with beginning and ending almost-blank lines.
|
||||
*/
|
||||
```
|
||||
|
||||
It's also important to comment data, whether they are basic types or
|
||||
derived types. To this end, use just one data declaration per line (no
|
||||
commas for multiple data declarations). This leaves you room for a small
|
||||
comment on each item, explaining its use.
|
||||
|
||||
## You've made a mess of it
|
||||
That's OK, we all do. You've probably been told by your long-time Unix user
|
||||
helper that "GNU emacs" automatically formats the C sources for you, and
|
||||
you've noticed that yes, it does do that, but the defaults it uses are less
|
||||
than desirable (in fact, they are worse than random typing - an infinite
|
||||
number of monkeys typing into GNU emacs would never make a good program).
|
||||
|
||||
So, you can either get rid of GNU emacs, or change it to use saner values.
|
||||
To do the latter, you can stick the following in your .emacs file:
|
||||
|
||||
```lisp
|
||||
(defun c-lineup-arglist-tabs-only (ignored)
|
||||
"Line up argument lists by tabs, not spaces"
|
||||
(let* ((anchor (c-langelem-pos c-syntactic-element))
|
||||
(column (c-langelem-2nd-pos c-syntactic-element))
|
||||
(offset (- (1+ column) anchor))
|
||||
(steps (floor offset c-basic-offset)))
|
||||
(* (max steps 1)
|
||||
c-basic-offset)))
|
||||
|
||||
(add-hook 'c-mode-common-hook
|
||||
(lambda ()
|
||||
;; Add kernel style
|
||||
(c-add-style
|
||||
"linux-tabs-only"
|
||||
'("linux" (c-offsets-alist
|
||||
(arglist-cont-nonempty
|
||||
c-lineup-gcc-asm-reg
|
||||
c-lineup-arglist-tabs-only))))))
|
||||
|
||||
(add-hook 'c-mode-hook
|
||||
(lambda ()
|
||||
(let ((filename (buffer-file-name)))
|
||||
;; Enable kernel mode for the appropriate files
|
||||
(when (and filename
|
||||
(string-match (expand-file-name "~/src/linux-trees")
|
||||
filename))
|
||||
(setq indent-tabs-mode t)
|
||||
(c-set-style "linux-tabs-only")))))
|
||||
```
|
||||
|
||||
This will make emacs go better with the kernel coding style for C files
|
||||
below ~/src/linux-trees.
|
||||
|
||||
But even if you fail in getting emacs to do sane formatting, not
|
||||
everything is lost: use "indent".
|
||||
|
||||
Now, again, GNU indent has the same brain-dead settings that GNU emacs
|
||||
has, which is why you need to give it a few command line options.
|
||||
However, that's not too bad, because even the makers of GNU indent
|
||||
recognize the authority of K&R (the GNU people aren't evil, they are
|
||||
just severely misguided in this matter), so you just give indent the
|
||||
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
|
||||
"scripts/Lindent", which indents in the latest style.
|
||||
|
||||
"indent" has a lot of options, and especially when it comes to comment
|
||||
re-formatting you may want to take a look at the man page. But remember:
|
||||
"indent" is not a fix for bad programming.
|
||||
|
||||
## Kconfig configuration files
|
||||
|
||||
For all of the Kconfig* configuration files throughout the source tree,
|
||||
the indentation is somewhat different. Lines under a "config"
|
||||
definition are indented with one tab, while help text is indented an
|
||||
additional two spaces. Example:
|
||||
|
||||
```kconfig
|
||||
config AUDIT
|
||||
bool "Auditing support"
|
||||
depends on NET
|
||||
help
|
||||
Enable auditing infrastructure that can be used with another
|
||||
kernel subsystem, such as SELinux (which requires this for
|
||||
logging of avc messages output). Does not do system-call
|
||||
auditing without CONFIG_AUDITSYSCALL.
|
||||
```
|
||||
|
||||
Seriously dangerous features (such as write support for certain
|
||||
filesystems) should advertise this prominently in their prompt string:
|
||||
|
||||
```kconfig
|
||||
config ADFS_FS_RW
|
||||
bool "ADFS write support (DANGEROUS)"
|
||||
depends on ADFS_FS
|
||||
...
|
||||
```
|
||||
|
||||
For full documentation on the configuration files, see the file
|
||||
Documentation/kbuild/kconfig-language.txt.
|
||||
|
||||
Data structures
|
||||
---------------
|
||||
|
||||
Data structures that have visibility outside the single-threaded
|
||||
environment they are created and destroyed in should always have
|
||||
reference counts. In the kernel, garbage collection doesn't exist (and
|
||||
outside the kernel garbage collection is slow and inefficient), which
|
||||
means that you absolutely _have_ to reference count all your uses.
|
||||
|
||||
Reference counting means that you can avoid locking, and allows multiple
|
||||
users to have access to the data structure in parallel - and not having
|
||||
to worry about the structure suddenly going away from under them just
|
||||
because they slept or did something else for a while.
|
||||
|
||||
Note that locking is _not_ a replacement for reference counting.
|
||||
Locking is used to keep data structures coherent, while reference
|
||||
counting is a memory management technique. Usually both are needed, and
|
||||
they are not to be confused with each other.
|
||||
|
||||
Many data structures can indeed have two levels of reference counting,
|
||||
when there are users of different "classes". The subclass count counts
|
||||
the number of subclass users, and decrements the global count just once
|
||||
when the subclass count goes to zero.
|
||||
|
||||
Examples of this kind of "multi-level-reference-counting" can be found
|
||||
in memory management ("struct mm_struct": mm_users and mm_count),
|
||||
and in filesystem code ("struct super_block": s_count and
|
||||
s_active).
|
||||
|
||||
Remember: if another thread can find your data structure, and you don't
|
||||
have a reference count on it, you almost certainly have a bug.
|
||||
|
||||
Macros, Enums and RTL
|
||||
---------------------
|
||||
|
||||
Names of macros defining constants and labels in enums are capitalized.
|
||||
|
||||
```c
|
||||
#define CONSTANT 0x12345
|
||||
```
|
||||
|
||||
Enums are preferred when defining several related constants.
|
||||
|
||||
CAPITALIZED macro names are appreciated but macros resembling functions
|
||||
may be named in lower case.
|
||||
|
||||
Generally, inline functions are preferable to macros resembling
|
||||
functions.
|
||||
|
||||
Macros with multiple statements should be enclosed in a do - while
|
||||
block:
|
||||
|
||||
```c
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
```
|
||||
|
||||
Things to avoid when using macros:
|
||||
|
||||
1) macros that affect control flow:
|
||||
|
||||
```c
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
```
|
||||
|
||||
is a *very* bad idea. It looks like a function call but exits the
|
||||
"calling" function; don't break the internal parsers of those who
|
||||
will read the code.
|
||||
|
||||
2) macros that depend on having a local variable with a magic name:
|
||||
|
||||
```c
|
||||
#define FOO(val) bar(index, val)
|
||||
```
|
||||
|
||||
might look like a good thing, but it's confusing as hell when one reads
|
||||
the code and it's prone to breakage from seemingly innocent changes.
|
||||
|
||||
3) macros with arguments that are used as l-values: FOO(x) = y; will
|
||||
bite you if somebody e.g. turns FOO into an inline function.
|
||||
|
||||
4) forgetting about precedence: macros defining constants using
|
||||
expressions must enclose the expression in parentheses. Beware of
|
||||
similar issues with macros using parameters.
|
||||
|
||||
```c
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
```
|
||||
|
||||
The cpp manual deals with macros exhaustively. The gcc internals manual
|
||||
also covers RTL which is used frequently with assembly language in the
|
||||
kernel.
|
||||
|
||||
Printing kernel messages
|
||||
------------------------
|
||||
|
||||
Kernel developers like to be seen as literate. Do mind the spelling of
|
||||
kernel messages to make a good impression. Do not use crippled words
|
||||
like "dont"; use "do not" or "don't" instead. Make the messages
|
||||
concise, clear, and unambiguous.
|
||||
|
||||
Kernel messages do not have to be terminated with a period.
|
||||
|
||||
Printing numbers in parentheses (%d) adds no value and should be
|
||||
avoided.
|
||||
|
||||
There are a number of driver model diagnostic macros in
|
||||
<linux/device.h> which you should use to make sure messages are
|
||||
matched to the right device and driver, and are tagged with the right
|
||||
level: dev_err(), dev_warn(), dev_info(), and so forth. For messages
|
||||
that aren't associated with a particular device, <linux/printk.h>
|
||||
defines pr_debug() and pr_info().
|
||||
|
||||
Coming up with good debugging messages can be quite a challenge; and
|
||||
once you have them, they can be a huge help for remote troubleshooting.
|
||||
Such messages should be compiled out when the DEBUG symbol is not
|
||||
defined (that is, by default they are not included). When you use
|
||||
dev_dbg() or pr_debug(), that's automatic. Many subsystems have
|
||||
Kconfig options to turn on -DDEBUG. A related convention uses
|
||||
VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled
|
||||
by DEBUG.
|
||||
|
||||
Allocating memory
|
||||
-----------------
|
||||
|
||||
coreboot provides a single general purpose memory allocator: malloc()
|
||||
|
||||
The preferred form for passing a size of a struct is the following:
|
||||
|
||||
```c
|
||||
p = malloc(sizeof(*p));
|
||||
```
|
||||
|
||||
The alternative form where struct name is spelled out hurts readability
|
||||
and introduces an opportunity for a bug when the pointer variable type
|
||||
is changed but the corresponding sizeof that is passed to a memory
|
||||
allocator is not.
|
||||
|
||||
Casting the return value which is a void pointer is redundant. The
|
||||
conversion from void pointer to any other pointer type is guaranteed by
|
||||
the C programming language.
|
||||
|
||||
You should contain your memory usage to stack variables whenever
|
||||
possible. Only use malloc() as a last resort. In ramstage, you may also
|
||||
be able to get away with using static variables. Never use malloc()
|
||||
outside of ramstage.
|
||||
|
||||
Since coreboot only runs for a very short time, there is no memory
|
||||
deallocator, although a corresponding free() is offered. It is a no-op.
|
||||
Use of free() is not required though it is accepted. It is useful when
|
||||
sharing code with other codebases that make use of free().
|
||||
|
||||
The inline disease
|
||||
------------------
|
||||
|
||||
There appears to be a common misperception that gcc has a magic "make
|
||||
me faster" speedup option called "inline". While the use of inlines
|
||||
can be appropriate (for example as a means of replacing macros, see
|
||||
Chapter 12), it very often is not. Abundant use of the inline keyword
|
||||
leads to a much bigger kernel, which in turn slows the system as a whole
|
||||
down, due to a bigger icache footprint for the CPU and simply because
|
||||
there is less memory available for the pagecache. Just think about it; a
|
||||
pagecache miss causes a disk seek, which easily takes 5 milliseconds.
|
||||
There are a LOT of cpu cycles that can go into these 5 milliseconds.
|
||||
|
||||
A reasonable rule of thumb is to not put inline at functions that have
|
||||
more than 3 lines of code in them. An exception to this rule are the
|
||||
cases where a parameter is known to be a compiletime constant, and as a
|
||||
result of this constantness you *know* the compiler will be able to
|
||||
optimize most of your function away at compile time. For a good example
|
||||
of this later case, see the kmalloc() inline function.
|
||||
|
||||
Often people argue that adding inline to functions that are static and
|
||||
used only once is always a win since there is no space tradeoff. While
|
||||
this is technically correct, gcc is capable of inlining these
|
||||
automatically without help, and the maintenance issue of removing the
|
||||
inline when a second user appears outweighs the potential value of the
|
||||
hint that tells gcc to do something it would have done anyway.
|
||||
|
||||
Function return values and names
|
||||
--------------------------------
|
||||
|
||||
Functions can return values of many different kinds, and one of the most
|
||||
common is a value indicating whether the function succeeded or failed.
|
||||
Such a value can be represented as an error-code integer (-Exxx =
|
||||
failure, 0 = success) or a "succeeded" boolean (0 = failure, non-zero
|
||||
= success).
|
||||
|
||||
Mixing up these two sorts of representations is a fertile source of
|
||||
difficult-to-find bugs. If the C language included a strong distinction
|
||||
between integers and booleans then the compiler would find these
|
||||
mistakes for us... but it doesn't. To help prevent such bugs, always
|
||||
follow this convention:
|
||||
|
||||
If the name of a function is an action or an imperative command,
|
||||
the function should return an error-code integer. If the name
|
||||
is a predicate, the function should return a "succeeded" boolean.
|
||||
|
||||
For example, "add work" is a command, and the add_work() function
|
||||
returns 0 for success or -EBUSY for failure. In the same way, "PCI
|
||||
device present" is a predicate, and the pci_dev_present() function
|
||||
returns 1 if it succeeds in finding a matching device or 0 if it
|
||||
doesn't.
|
||||
|
||||
All EXPORTed functions must respect this convention, and so should all
|
||||
public functions. Private (static) functions need not, but it is
|
||||
recommended that they do.
|
||||
|
||||
Functions whose return value is the actual result of a computation,
|
||||
rather than an indication of whether the computation succeeded, are not
|
||||
subject to this rule. Generally they indicate failure by returning some
|
||||
out-of-range result. Typical examples would be functions that return
|
||||
pointers; they use NULL or the ERR_PTR mechanism to report failure.
|
||||
|
||||
Don't re-invent the kernel macros
|
||||
----------------------------------
|
||||
|
||||
The header file include/linux/kernel.h contains a number of macros that
|
||||
you should use, rather than explicitly coding some variant of them
|
||||
yourself. For example, if you need to calculate the length of an array,
|
||||
take advantage of the macro
|
||||
|
||||
```c
|
||||
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
|
||||
```
|
||||
|
||||
There are also min() and max() macros that do strict type checking if
|
||||
you need them. Feel free to peruse that header file to see what else is
|
||||
already defined that you shouldn't reproduce in your code.
|
||||
|
||||
Editor modelines and other cruft
|
||||
--------------------------------
|
||||
|
||||
Some editors can interpret configuration information embedded in source
|
||||
files, indicated with special markers. For example, emacs interprets
|
||||
lines marked like this:
|
||||
|
||||
```
|
||||
-*- mode: c -*-
|
||||
```
|
||||
|
||||
Or like this:
|
||||
|
||||
```
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
```
|
||||
|
||||
Vim interprets markers that look like this:
|
||||
|
||||
```
|
||||
/* vim:set sw=8 noet */
|
||||
```
|
||||
|
||||
Do not include any of these in source files. People have their own
|
||||
personal editor configurations, and your source files should not
|
||||
override them. This includes markers for indentation and mode
|
||||
configuration. People may use their own custom mode, or may have some
|
||||
other magic method for making indentation work correctly.
|
||||
|
||||
Inline assembly
|
||||
---------------
|
||||
|
||||
In architecture-specific code, you may need to use inline assembly to
|
||||
interface with CPU or platform functionality. Don't hesitate to do so
|
||||
when necessary. However, don't use inline assembly gratuitously when C
|
||||
can do the job. You can and should poke hardware from C when possible.
|
||||
|
||||
Consider writing simple helper functions that wrap common bits of inline
|
||||
assembly, rather than repeatedly writing them with slight variations.
|
||||
Remember that inline assembly can use C parameters.
|
||||
|
||||
Large, non-trivial assembly functions should go in .S files, with
|
||||
corresponding C prototypes defined in C header files. The C prototypes
|
||||
for assembly functions should use "asmlinkage".
|
||||
|
||||
You may need to mark your asm statement as volatile, to prevent GCC from
|
||||
removing it if GCC doesn't notice any side effects. You don't always
|
||||
need to do so, though, and doing so unnecessarily can limit
|
||||
optimization.
|
||||
|
||||
When writing a single inline assembly statement containing multiple
|
||||
instructions, put each instruction on a separate line in a separate
|
||||
quoted string, and end each string except the last with nt to
|
||||
properly indent the next instruction in the assembly output:
|
||||
|
||||
```c
|
||||
asm ("magic %reg1, #42nt"
|
||||
"more_magic %reg2, %reg3"
|
||||
: /* outputs */ : /* inputs */ : /* clobbers */);
|
||||
```
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
The C Programming Language, Second Edition by Brian W. Kernighan and
|
||||
Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8
|
||||
(paperback), 0-13-110370-9 (hardback). URL:
|
||||
<http://cm.bell-labs.com/cm/cs/cbook/>
|
||||
|
||||
The Practice of Programming by Brian W. Kernighan and Rob Pike.
|
||||
Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. URL:
|
||||
<http://cm.bell-labs.com/cm/cs/tpop/>
|
||||
|
||||
GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
|
||||
gcc internals and indent, all available from
|
||||
<http://www.gnu.org/manual/>
|
||||
|
||||
WG14 is the international standardization working group for the
|
||||
programming language C, URL: <http://www.open-std.org/JTC1/SC22/WG14/>
|
||||
|
||||
Kernel CodingStyle, by greg@kroah.com at OLS 2002:
|
||||
<http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/>
|
||||
@@ -1,118 +0,0 @@
|
||||
# Code of Conduct
|
||||
|
||||
This code of conduct outlines our rules and expectations for everybody
|
||||
participating in the coreboot community.
|
||||
|
||||
## coreboot community etiquette
|
||||
|
||||
We have a friendly and productive atmosphere on our mailing lists,
|
||||
development / code review tools, IRC chat rooms and when we meet in
|
||||
person. Our principles evolve around the following:
|
||||
|
||||
* It's not the user's fault if something goes wrong.
|
||||
* Attempt collaboration before conflict.
|
||||
* People who intentionally insult others (users, developers, corporations,
|
||||
other projects, or the coreboot project itself) will be dealt with. See
|
||||
policy below.
|
||||
* We are dealing with hardware with lots of undocumented pitfalls. It is quite
|
||||
possible that you did everything right, but coreboot or its tools still
|
||||
won't work for you.
|
||||
|
||||
Refrain from insulting anyone or the group they belong to. Remember that
|
||||
people might be sensitive to other things than you are.
|
||||
|
||||
Most of our community members are not native English speakers, thus
|
||||
misunderstandings can (and do) happen. Assume that others are friendly
|
||||
and may have picked less-than-stellar wording by accident as long as
|
||||
you possibly can.
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
If you have a grievance due to conduct in this community, we're sorry
|
||||
that you have had a bad experience, and we want to hear about it so
|
||||
we can resolve the situation.
|
||||
|
||||
Please contact members of our arbitration team (listed below) promptly
|
||||
and directly, in person (if available) or by email: They will listen
|
||||
to you and react in a timely fashion.
|
||||
|
||||
If you feel uncomfortable, please don't wait it out, ask for help,
|
||||
so we can work on setting things right.
|
||||
|
||||
For transparency there is no alias or private mailing list address for
|
||||
you to reach out to, since we want to make sure that you know who will
|
||||
and who won't read your message.
|
||||
|
||||
However since people might be on travel or otherwise be unavailable
|
||||
at times, please reach out to multiple persons at once, especially
|
||||
when using email.
|
||||
|
||||
The team will treat your messages confidential as far as the law permits.
|
||||
For the purpose of knowing what law applies, the list provides the usual
|
||||
country of residence of each team member.
|
||||
|
||||
## Unacceptable Behavior
|
||||
|
||||
Unacceptable behaviors include: intimidating, harassing, abusive,
|
||||
discriminatory, derogatory or demeaning speech or actions by any
|
||||
participant in our community online, at all related events and in
|
||||
one-on-one communications carried out in the context of community
|
||||
business. Community event venues may be shared with members of the public;
|
||||
please be respectful to all patrons of these locations.
|
||||
|
||||
Examples of behaviors we do not accept in our community:
|
||||
|
||||
* harmful or prejudicial verbal or written comments related to gender,
|
||||
sexual orientation, race, religion, disability;
|
||||
* inappropriate physical contact, and unwelcome sexual advances;
|
||||
* deliberate intimidation, stalking or following;
|
||||
* harassing photography or recording;
|
||||
* sustained disruption of talks or other events.
|
||||
|
||||
Using this code of conduct aggressively against other people in the
|
||||
community might also be harassment. Be considerate when enforcing the code
|
||||
of conduct and always try to listen to both sides before passing judgment.
|
||||
|
||||
## Consequences of Unacceptable Behavior
|
||||
|
||||
Unacceptable behavior from any community member, including sponsors and
|
||||
those with decision-making authority, will not be tolerated.
|
||||
|
||||
Anyone asked to stop unacceptable behavior is expected to comply
|
||||
immediately.
|
||||
|
||||
If a community member engages in unacceptable behavior, the community
|
||||
organizers may take any action they deem appropriate, up to and including
|
||||
a temporary ban or permanent expulsion from the community without warning
|
||||
(and without refund in the case of a paid event).
|
||||
|
||||
Community organizers can be members of the arbitration team, or organizers
|
||||
of events and online communities.
|
||||
|
||||
## Addressing Grievances
|
||||
|
||||
If you feel you have been falsely or unfairly accused of violating this
|
||||
Code of Conduct, you should notify the arbitration team with a concise
|
||||
description of your grievance.
|
||||
|
||||
## Scope
|
||||
|
||||
We expect all community participants (contributors, paid or otherwise;
|
||||
sponsors; and other guests) to abide by this Code of Conduct in all
|
||||
community venues, online and in-person, as well as in all one-on-one
|
||||
communications pertaining to community business.
|
||||
|
||||
## Contact info
|
||||
|
||||
Our arbitration team consists of the following people
|
||||
* Stefan Reinauer <stefan.reinauer@coreboot.org> (USA)
|
||||
* Patrick Georgi <patrick@coreboot.org> (Germany)
|
||||
* Ronald Minnich <rminnich@coreboot.org> (USA)
|
||||
* Martin Roth <martin@coreboot.org> (USA)
|
||||
|
||||
## License and attribution
|
||||
|
||||
This Code of Conduct is distributed under
|
||||
a [Creative Commons Attribution-ShareAlike
|
||||
license](http://creativecommons.org/licenses/by-sa/3.0/). It is based
|
||||
on the [Citizen Code of Conduct](http://citizencodeofconduct.org/)
|
||||
@@ -1,70 +0,0 @@
|
||||
# Conferences
|
||||
The coreboot community is present at a number of conferences over the year,
|
||||
usually at [FOSDEM](https://fosdem.org), [OSFC](https://osfc.io), and the
|
||||
[Chaos Communication Congress](https://events.ccc.de/congress/).
|
||||
|
||||
The kind of presence differs, but there's usually a booth or other kind of
|
||||
gathering where everybody is welcome to say hello and to learn more about
|
||||
coreboot.
|
||||
|
||||
Depending on the nature of the conference, coreboot developers might bring
|
||||
their development kit with them and conduct development sessions.
|
||||
|
||||
## Talks
|
||||
|
||||
[Open Source Firmware at Facebook](https://fosdem.org/2019/schedule/event/open_source_firmware_at_facebook/) by [David Hendricks](https://github.com/dhendrix) and [Andrea Barberio](https://github.com/insomniacslk) at [FOSDEM 2019](https://fosdem.org/2019/) ([video](https://video.fosdem.org/2019/K.4.401/open_source_firmware_at_facebook.mp4)) ([slides](https://insomniac.slackware.it/static/2019_fosdem_linuxboot_at_facebook.pdf)) (2019-02-03)
|
||||
|
||||
[Open Source Firmware - A love story](https://www.youtube.com/watch?v=xfqKm190dbU) by [Philipp Deppenwiese](https://cybersecurity.9elements.com) at [35c3](https://events.ccc.de/congress/2018)
|
||||
([slides](https://cdn.media.ccc.de/congress/2018/slides-h264-hd/35c3-9778-deu-eng-Open_Source_Firmware_hd-slides.mp4)) (2018-12-27)
|
||||
|
||||
[coreboot mainboard porting with Intel FSP 2.0](https://www.youtube.com/watch?v=qUgo-AVsSCI) by Subrata Banik at OSFC 2018
|
||||
|
||||
[A tale of reusability in coreboot](https://www.youtube.com/watch?v=p2bnEYKBDpI) by Furquan Shaikh at OSFC 2018
|
||||
|
||||
[How to enable AMD IOMMU in coreboot](https://www.youtube.com/watch?v=5JoEuh9qXx0) by Piotr Król at OSFC 2018
|
||||
|
||||
[ARM Trusted Firmware for coreboot developers](https://www.youtube.com/watch?v=UC35q4OJg3k) by Julius Werner at OSFC 2018
|
||||
|
||||
[Google Secure Microcontroller and Case Closed Debugging](https://www.youtube.com/watch?v=gC-lbMNmIsg) by Vadim Bendebury at OSFC 2018
|
||||
|
||||
[coreboot rompayload](https://www.youtube.com/watch?v=ukSh1n7wjSA) by Ron Minnich at OSFC 2018
|
||||
|
||||
[Run upstream coreboot on an ARM Chromebook](https://www.youtube.com/watch?v=N7_9okzPeHo) by Paul Menzel at ECC 2017
|
||||
|
||||
[DDR3 memory initialization basics on Intel Sandybrige platforms](https://www.youtube.com/watch?v=h-Lkkg03Erk) by Patrick Rudolph at ECC 2017
|
||||
|
||||
[Let's move SMM out of firmware and into the kernel](https://www.youtube.com/watch?v=6GEaw4msq6g) by Ron Minnich at ECC 2017
|
||||
|
||||
[SINUMERIK – step ahead with coreboot](https://www.youtube.com/watch?v=tq4xSipCWEU) by Werner Zeh at ECC 2017
|
||||
|
||||
[Booting UEFI-aware OS on coreboot enabled platform](https://www.youtube.com/watch?v=nt0BkqVUu3w) by Piotr Król and Kamil Wcisło at ECC 2017
|
||||
|
||||
[Reverse engineering MT8173 PCM firmwares and ISA for a fully free bootchain](https://www.youtube.com/watch?v=9rKxfo7Gkqo) by Paul Kocialkowski at ECC 2017
|
||||
|
||||
[A Tale of six motherboards, two BSDs and coreboot](https://www.youtube.com/watch?v=jlCGzML6zF8) by Piotr Kubaj at ECC 2017
|
||||
|
||||
[Enabling TPM 2.0 on coreboot based devices](https://www.youtube.com/watch?v=Yjb9n5p3giI) by Piotr Król and Kamil Wcisło at ECC 2017
|
||||
|
||||
[Porting coreboot to the HP ProLiant MicroServer Gen8](https://www.youtube.com/watch?v=BcmUSW2J53k) by Alexander Couzens and Felix Held at ECC 2017
|
||||
|
||||
[Implementing coreboot in a ground breaking secure system: ORWL](https://www.youtube.com/watch?v=D4oQjcP6AVI) by Wim Vervoorn and Gerard Duynisveld at ECC 2017
|
||||
|
||||
[Buying trustworthy hardware for federal agencies: How open source firmware saves the day](https://www.youtube.com/watch?v=DG_wfaw4zl0) by Carl-Daniel Hailfinger at ECC 2017
|
||||
|
||||
[Verified Boot: Surviving in the Internet of Insecure Things: Randall Spangler](https://www.youtube.com/watch?v=4EvTcfcYfMY) by Randall Spangler at coreboot conference 2016
|
||||
|
||||
[coreboot on RISC-V](https://www.youtube.com/watch?v=CDNIWuf1jAk) by Ron Minnich at coreboot conference 2016
|
||||
|
||||
[An Open Source Embedded Controller](https://www.youtube.com/watch?v=hQb8waUBVSQ) by Bill Richardson at coreboot conference 2016
|
||||
|
||||
[KB9012 EC Firmware Reverse Engineering](https://www.youtube.com/watch?v=B708jdCiW7o) by Paul Kocialkowski at coreboot conference 2016
|
||||
|
||||
[coreboot on ARM](https://www.youtube.com/watch?v=z-KpAA4_afs) by Julius Werner at coreboot conference 2016
|
||||
|
||||
[Intel FSP 2.0 overview](https://www.youtube.com/watch?v=uzfiTiP9dEM) by Giri Mudusuru and Vincent Zimmer at coreboot conference 2016
|
||||
|
||||
[coreboot Internals](https://www.youtube.com/watch?v=7YUXr1MH9d4) by Aaron Durbin at coreboot conference 2016
|
||||
|
||||
[Skylake FSP to coreboot integration overview](https://www.youtube.com/watch?v=SpL8LbquSVs) by Robbie Zhang at coreboot conference 2016
|
||||
|
||||
[S3 implementation on Braswell](https://www.youtube.com/watch?v=GfwTijFnFl0) by Hannah Williams at coreboot conference 2016
|
||||
@@ -1,18 +0,0 @@
|
||||
# Our forums
|
||||
|
||||
The coreboot community has various venues to help each other and discuss the
|
||||
direction of our project.
|
||||
|
||||
## Mailing list
|
||||
|
||||
The first address for coreboot related discussion is our mailing list.
|
||||
You can subscribe on its
|
||||
[information page](https://mail.coreboot.org/postorius/lists/coreboot.coreboot.org/) and
|
||||
read its
|
||||
[archives](https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/).
|
||||
|
||||
## IRC
|
||||
|
||||
We also have a
|
||||
[real time chat](https://webchat.freenode.net?channels=%23coreboot)
|
||||
on the Freenode IRC network's #coreboot channel.
|
||||
@@ -1,136 +0,0 @@
|
||||
# Language style
|
||||
|
||||
Following our [Code of Conduct](code_of_conduct.md) the project aims to
|
||||
be a space where people are considerate in natural language communication:
|
||||
|
||||
There are terms in computing that were probably considered benign when
|
||||
introduced but are uncomfortable to some. The project aims to de-emphasize
|
||||
such terms in favor of alternatives that are at least as expressive -
|
||||
but often manage to be even more descriptive.
|
||||
|
||||
## Political Correctness
|
||||
|
||||
A common thread in discussions was that the project merely follows some
|
||||
fad, or that this is a "political correctness" measure, designed to please
|
||||
one particular "team". While the project doesn't exist in a vacuum and
|
||||
so there are outside influences on project members, the proposal wasn't
|
||||
made with the purpose of demonstrating allegiance to any given cause -
|
||||
except one:
|
||||
|
||||
There are people who feel uncomfortable with some terms being used,
|
||||
_especially_ when that use takes them out of their grave context
|
||||
(e.g. slave when discussing slavery) and applies them to a rather benign
|
||||
topic (e.g. coordination of multiple technical systems), taking away
|
||||
the gravity of the term.
|
||||
|
||||
That gets especially jarring when people aren't exposed to such terms
|
||||
in abstract sociological discussions but when they stand for real issues
|
||||
they encountered.
|
||||
|
||||
When having to choose between using a well-established term that
|
||||
affects people negatively who could otherwise contribute more happily
|
||||
and undisturbed or an alternative just-as-good term that doesn't, the
|
||||
decision should be simple.
|
||||
|
||||
## Token gesture
|
||||
|
||||
The other major point of contention is that such decisions are a token
|
||||
gesture that doesn't change anything. It's true: No slave is freed
|
||||
because coreboot rejects the use of the word.
|
||||
|
||||
coreboot is ambitious enough as-is, in that the project offers
|
||||
an alternative approach to firmware, sometimes against the vested
|
||||
interests (and deep pockets) of the leaders of a multi-billion dollar
|
||||
industry. Changing the preferred vocabulary isn't another attempt at
|
||||
changing the world, it's one thing we do to try to make coreboot (and
|
||||
coreboot only) a comfortable environment for everybody.
|
||||
|
||||
## For everybody
|
||||
|
||||
For everybody, but with a qualifier: We have certain community etiquette,
|
||||
and we define some behavior we don't accept in our community, both
|
||||
detailed in the Code of Conduct.
|
||||
|
||||
Other than that, we're trying to accommodate people: The CoC lays out
|
||||
that language should be interpreted as friendly by default, and to be
|
||||
graceful in light of accidents. This also applies to the use of terms
|
||||
that the project tries to avoid: The consequence of the use of such
|
||||
terms (unless obviously employed to provoke a reaction - in that case,
|
||||
please contact the arbitration team as outlined in the Code of Conduct)
|
||||
should be a friendly reminder. The project is slow to sanction and that
|
||||
won't change just because the wrong kind of words is used.
|
||||
|
||||
## Interfacing with the world
|
||||
|
||||
The project doesn't exist in a vacuum, and that also applies to the choice
|
||||
of words made by other initiatives in low-level technology. When JEDEC
|
||||
calls the participants of a SPI transaction "master" and "slave", there's
|
||||
little we can do about that. We _could_ decide to use different terms,
|
||||
but that wouldn't make things easier but harder, because such a deliberate
|
||||
departure means that the original terms (and their original use) gain
|
||||
lots of visibility every time (so there's no practical advantage) while
|
||||
adding confusion, and therefore even more attention, to that situation.
|
||||
|
||||
Sometimes there are abbreviations that can be used as substitutes,
|
||||
and in that case the recommendation is to do that.
|
||||
|
||||
As terms that we found to be best avoided are replaced in such
|
||||
initiatives, we can follow up. Members of the community with leverage
|
||||
in such organizations are encouraged to raise the concern there.
|
||||
|
||||
## Dealing with uses
|
||||
|
||||
There are existing uses in our documentation and code. When we decide to
|
||||
retire a term that doesn't mean that everybody is supposed to stop doing
|
||||
whatever they're doing and spend their time on purging terms. Instead,
|
||||
ongoing development should look for alternatives (and so this could come
|
||||
up in review).
|
||||
|
||||
People can go through existing code and docs and sort out older instances,
|
||||
and while that's encouraged it's no "stop the world" event. Changes
|
||||
in flight in review may still be merged with such terms intact, but if
|
||||
there's more work required for other reasons, we'd encourage moving away
|
||||
from such terms.
|
||||
|
||||
This document has a section on retired terms, presenting the rationale
|
||||
as well as alternative terms that could be used instead. The main goal is
|
||||
to be expressive: There's no point in just picking any alternative term,
|
||||
choose something that explains the purpose well.
|
||||
|
||||
As mentioned, missteps will happen. Point them out, but assume no ill
|
||||
intent for as long as you can manage.
|
||||
|
||||
## Discussing words to remove from active use
|
||||
|
||||
There ought to be some process when terminology is brought up as a
|
||||
negative to avoid. Do not to tell people that "they're feeling wrong"
|
||||
when they have a negative reaction to certain terms, but also try to
|
||||
avoid being offended for the sake of others.
|
||||
|
||||
When bringing up a term, on the project's mailing list or, if you don't
|
||||
feel safe doing that, by contacting the arbitration team, explain what's
|
||||
wrong with the term and offer alternatives for uses within coreboot.
|
||||
|
||||
With a term under discussion, see if there's particular value for us to
|
||||
continue using the term (maybe in limited situations, like continuing
|
||||
to use "slave" in SPI related code).
|
||||
|
||||
Once the arbitration team considers the topic discussed completely and
|
||||
found a consensus, it will present a decision in a leadership meeting. It
|
||||
should explain why a term should or should not be used and in the latter
|
||||
case offer alternatives. These decisions shall then be added to this
|
||||
document.
|
||||
|
||||
## Retired terminology
|
||||
|
||||
### slave
|
||||
|
||||
Replacing this term for something else had the highest approval rating
|
||||
in early discussions, so it seems pretty universally considered a bad
|
||||
choice and therefore should be avoided where possible.
|
||||
|
||||
An exception is made where it's a term used in current standards and data
|
||||
sheets: Trying to "hide" the term in such cases only puts a spotlight
|
||||
on it every time code and data sheet are compared.
|
||||
|
||||
Alternatives: subordinate, secondary, follower
|
||||
@@ -1,45 +0,0 @@
|
||||
# Accounts on coreboot.org
|
||||
|
||||
There are a number of places where you can benefit from creaating an account
|
||||
in our community. Since there is no single sign-on system in place (at this
|
||||
time), they come with their own setup routines.
|
||||
|
||||
## Gerrit code review
|
||||
We exchange and review patches to the code using our [Gerrit code review
|
||||
system](https://review.coreboot.org).
|
||||
|
||||
It allows logging in with a Google or GitHub account using OAuth2 as well
|
||||
as with any OpenID provider that you may already use.
|
||||
|
||||
On the [settings screen](https://review.coreboot.org/settings) you can register
|
||||
all your email addresses you intend to use in the context of coreboot
|
||||
development so that commits with your email address in them are associated with
|
||||
you properly.
|
||||
|
||||
### https push access
|
||||
When using the https URLs to git repositories, you can push with the "HTTP
|
||||
Credentials" you can have Gerrit generate for you on that page. By default,
|
||||
git uses `$HOME/.netrc` for http authentication data, so add a line there
|
||||
stating:
|
||||
|
||||
machine review.coreboot.org login $your-user-name password $your-password
|
||||
|
||||
### Gerrit user avatar
|
||||
To setup an avatar to show in Gerrit, clone the avatars repository at
|
||||
https://review.coreboot.org/gerrit-avatars.git and add a file named
|
||||
$your-user-ID.jpg (the user ID is a number shown on the [settings screen](https://review.coreboot.org/settings)).
|
||||
The image must be provided in JPEG format, must be square and have at most 50000
|
||||
bytes.
|
||||
|
||||
After you push for review, the system will automatically verify your change
|
||||
and, if adhering to these constraints, approve it. You can then immediately
|
||||
submit it.
|
||||
|
||||
## Issue tracker
|
||||
We have an [issue tracker](https://ticket.coreboot.org) that is used for
|
||||
coreboot and related code, such as libpayload, as well as for the project's
|
||||
infrastructure.
|
||||
|
||||
It can be helpful to refer to issues we track there in commit messages:
|
||||
|
||||
Fixes: https://ticket.coreboot.org/issues/$id
|
||||
@@ -1,18 +1,4 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
import subprocess
|
||||
from recommonmark.parser import CommonMarkParser
|
||||
import sphinx
|
||||
|
||||
# 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']
|
||||
@@ -25,30 +11,17 @@ master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'coreboot'
|
||||
copyright = u'CC-by 4.0 the coreboot project'
|
||||
copyright = u'the coreboot project'
|
||||
author = u'the coreboot project'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = subprocess.check_output(('git', 'describe')).decode("utf-8")
|
||||
# The short X.Y version.
|
||||
version = release.split("-")[0]
|
||||
|
||||
extensions = []
|
||||
# Load recommonmark, supported since 1.8+
|
||||
if major >= 2 or (major == 1 and minor >= 8):
|
||||
extensions += ['recommonmark']
|
||||
|
||||
# Try to load DITAA
|
||||
try:
|
||||
import sphinxcontrib.ditaa
|
||||
except ImportError:
|
||||
print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
|
||||
else:
|
||||
extensions += ['sphinxcontrib.ditaa']
|
||||
version = u'4.7'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = u'4.7' # TODO: use 'git describe'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
@@ -146,7 +119,7 @@ latex_documents = [
|
||||
#
|
||||
# latex_appendices = []
|
||||
|
||||
# If false, will not define \strong, \code, itleref, \crossref ... but only
|
||||
# It false, will not define \strong, \code, itleref, \crossref ... but only
|
||||
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
|
||||
# packages.
|
||||
#
|
||||
@@ -182,14 +155,9 @@ texinfo_documents = [
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
enable_auto_toc_tree = True
|
||||
|
||||
class MyCommonMarkParser(CommonMarkParser):
|
||||
# remove this hack once upsteam RecommonMark supports inline code
|
||||
def visit_code(self, mdnode):
|
||||
from docutils import nodes
|
||||
n = nodes.literal(mdnode.literal, mdnode.literal)
|
||||
self.current_node.append(n)
|
||||
source_parsers = {
|
||||
'.md': 'recommonmark.parser.CommonMarkParser',
|
||||
}
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#
|
||||
@@ -207,16 +175,14 @@ class MyCommonMarkParser(CommonMarkParser):
|
||||
#
|
||||
# texinfo_no_detailmenu = False
|
||||
|
||||
enable_auto_toc_tree = True
|
||||
|
||||
|
||||
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_auto_doc_ref': True,
|
||||
'enable_eval_rst': True,
|
||||
'url_resolver': lambda url: '/' + url
|
||||
}, True)
|
||||
|
||||
@@ -1,173 +0,0 @@
|
||||
# Documentation Ideas
|
||||
|
||||
This section collects ideas to improve the coreboot documentation and
|
||||
should serve as a pool of ideas for people who want to improve the current
|
||||
documentation status of coreboot.
|
||||
|
||||
The main purpose of this document is to gather documentation ideas for technical
|
||||
writers of the seasons of docs. Nevertheless anyone who wants to help improving
|
||||
the current documentation situation can take one of the projects.
|
||||
|
||||
Each entry should outline what would be done, the benefit it brings
|
||||
to the project, the pre-requisites, both in knowledge and parts. They
|
||||
should also list people interested in supporting people who want to work
|
||||
on them.
|
||||
|
||||
## Restructure Existing Documentation
|
||||
|
||||
The goal is to improve the user experience and structure the documentation more
|
||||
logically. The current situation makes it very hard for beginners, but also for
|
||||
experienced developers to find anything in the coreboot documentation.
|
||||
|
||||
One possible approach to restructure the documentation is to split it up such
|
||||
that we divide the group of users into:
|
||||
|
||||
* (End-)users
|
||||
Most probably users which _just_ want to use coreboot as fast as possible. This
|
||||
section should include guidelines on how to build coreboot, how to flash coreboot
|
||||
and also which hardware is currently supported.
|
||||
|
||||
* Developers
|
||||
This section should more focus on the developer side-of-view. This section would
|
||||
include how to get started developing coreboot, explaining the basic concepts of
|
||||
coreboot and also give guideance on how to proceed after the first steps.
|
||||
|
||||
* Knowledge area
|
||||
This section is very tighlight coupled to the developer section and might be merged
|
||||
into it. The _Knowledge area_ can give a technical deep dive on various drivers,
|
||||
technologies, etc.
|
||||
|
||||
* Community area
|
||||
This section gives some room for the community: Youtube channels, conferences,
|
||||
meetups, forums, chat, etc.
|
||||
|
||||
A [first approach](https://review.coreboot.org/c/coreboot/+/40327) has already been made here and might be a basis for the work.
|
||||
Most of the documentation is already there, but scattered around the documentation
|
||||
folder.
|
||||
|
||||
### Requirements
|
||||
* Understanding on how a different groups of users might use the documentation area
|
||||
* Basic understanding of how coreboot works (Can be worked out _on-the-fly_)
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## Update Howto/Guides
|
||||
|
||||
An important part to involve new people in the project, either as developer or
|
||||
as enduser, are guides and how-to's. There are already some guides which need
|
||||
to be updated to work, and could also be extended to multiple platforms, like
|
||||
Fedora or Arch-Linux. Also guidance for setting up coreboot with a Windows
|
||||
environment would be helpful.
|
||||
|
||||
In addition, the vboot guidance needs an update/extensions, that the security
|
||||
features within coreboot can be used by non-technical people.
|
||||
|
||||
For developers, how to debug coreboot and various debugging techniques need
|
||||
documentation.
|
||||
|
||||
### Requirements
|
||||
* Knowledge of virtual machines, how to install different OSs and set up the
|
||||
toolchain on different operating systems
|
||||
* Knowledge of debugging tools like gdb
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## How to Support a New Board
|
||||
|
||||
coreboot benefits from running on as many platforms as possible. Therefore we
|
||||
want to encourage new developers on porting existing hardware to coreboot.
|
||||
Guidance for those new developers need to be made such that they are able to
|
||||
take the first steps supporting new mainboards, when the SoC support already
|
||||
exists. There should be a 'how-to' guide for this. Also what are common problems
|
||||
and how to solve those.
|
||||
|
||||
### Requirements
|
||||
* Knowledge of how to add support for a new mainboard in coreboot
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
## Payloads
|
||||
|
||||
The current documentation of the payloads is not very effective. There should be
|
||||
more detailed documentation on the payloads that can be selected via the make
|
||||
menuconfig within coreboot. Also the use-cases should be described in more
|
||||
detail: When to use which payload? What are the benefits of using payload X over
|
||||
Y in a specific use-case ?
|
||||
|
||||
In addition it should be made clear how additional functionality e.g. extend
|
||||
LinuxBoot with more commands, can be achieved.
|
||||
|
||||
### Requirements
|
||||
* Basic knowledge of the supported payloads like SeaBIOS, TinanoCore, LinuxBoot,
|
||||
GRUB, Linux, ...
|
||||
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
|
||||
## coreboot Util Documentation
|
||||
|
||||
coreboot inherits a variaty of utilities. The current documentation only
|
||||
provides a "one-liner" as an explanation. The list of util should be updated
|
||||
with a more detailed explanation where possible. Also more "in-depths"
|
||||
explanations should be added with examples if possible.
|
||||
|
||||
### Requirements
|
||||
* coreboot utilities
|
||||
|
||||
### Mentors
|
||||
* christian.walter@9elements.com
|
||||
* TBD
|
||||
|
||||
|
||||
## CBMEM Developer Guide
|
||||
|
||||
CBMEM is the API that provides memory buffers for the use at OS runtime. It's a
|
||||
core component and thus should be documented. Dos, don'ts and pitfalls when
|
||||
using CBMEM. This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
||||
|
||||
## CBFS Developer Guide
|
||||
|
||||
CBFS is the in-flash filesystem that is used by coreboot. It's a core component
|
||||
and thus should be documented. Update the existing CBFS.txt that still shows
|
||||
version 1 of the implementation. A [first approach](https://review.coreboot.org/c/coreboot/+/33663/2)
|
||||
has been made here.
|
||||
This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
||||
|
||||
## Region API Developer Guide
|
||||
|
||||
The region API is used by coreboot when dealing with memory mapped objects that
|
||||
can be split into chunks. It's a core component and thus should be documented.
|
||||
This "in-depth" guide is clearly for developers.
|
||||
|
||||
### Requirements
|
||||
* Deep understanding of coreboot's internals
|
||||
|
||||
### Mentors
|
||||
* TBD
|
||||
* TBD
|
||||
|
||||
@@ -1,249 +0,0 @@
|
||||
# Project Ideas
|
||||
|
||||
This section collects ideas to improve coreboot and related projects and
|
||||
should serve as a pool of ideas for people who want to enter the field
|
||||
of firmware development but need some guidance what to work on.
|
||||
|
||||
These tasks can be adopted as part of programs like Google Summer of
|
||||
Code or by motivated individuals outside such programs.
|
||||
|
||||
Each entry should outline what would be done, the benefit it brings
|
||||
to the project, the pre-requisites, both in knowledge and parts. They
|
||||
should also list people interested in supporting people who want to work
|
||||
on them - since we started building this list for Google Summer of Code,
|
||||
we'll adopt its term for those people and call them mentors.
|
||||
|
||||
The requirements for each project aim for productive work on the project,
|
||||
but it's always possible to learn them "on the job". If you have any
|
||||
doubt if you can bring yourself up to speed in a required time frame
|
||||
(e.g. for GSoC), feel free to ask in the community or the mentors listed
|
||||
with the projects. We can then try together to figure out if you're a
|
||||
good match for a project, even when requirements might not all be met.
|
||||
|
||||
## Provide toolchain binaries
|
||||
Our crossgcc subproject provides a uniform compiler environment for
|
||||
working on coreboot and related projects. Sadly, building it takes hours,
|
||||
which is a bad experience when trying to build coreboot the first time.
|
||||
|
||||
Provide packages/installers of our compiler toolchain for Linux distros,
|
||||
Windows, Mac OS. For Windows, this should also include the environment
|
||||
(shell, make, ...). A student doesn't have to cover _all_ platforms, but
|
||||
pick a set of systems that match their interest and knowledge and lay
|
||||
out a plan on how to do this.
|
||||
|
||||
The scripts to generate these packages should be usable on a Linux
|
||||
host, as that's what we're using for our automated build testing system
|
||||
that we could extend to provide current packages going forward. This
|
||||
might include automating some virtualization system (eg. QEMU or CrosVM) for
|
||||
non-Linux builds or Docker for different Linux distributions.
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Should know how to build coreboot images and where
|
||||
the compiler comes into play in our build system.
|
||||
* other knowledge: Should know how packages or installers for their
|
||||
target OS work. Knowledge of the GCC build system is a big plus
|
||||
* hardware requirements: Nothing special
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Support Power9/Power8 in coreboot
|
||||
There are some basic PPC64 stubs in coreboot, and there's open hardware
|
||||
in TALOS2 and its family. While they already have fully open source
|
||||
firmware, coreboot support adds a unified story for minimal firmware
|
||||
across architectures.
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Should be familiar with making chipset level
|
||||
changes to the code.
|
||||
* other knowledge: A general idea of the Power architecture, the more,
|
||||
the better
|
||||
* hardware requirements: QEMU Power bring-up exists, and even if it
|
||||
probably needs to be fixed up, that shouldn't be an exceedingly large
|
||||
task. For everything else, access to real Power8/9 hardware and recovery
|
||||
tools (e.g. for external flashing) is required.
|
||||
|
||||
### Mentors
|
||||
* Timothy Pearson <tpearson@raptorengineering.com>
|
||||
|
||||
## Add Kernel Address Sanitizer functionality to coreboot
|
||||
The Kernel Address Sanitizer (KASAN) is a runtime dynamic memory error detector.
|
||||
The idea is to check every memory access (variables) for its validity
|
||||
during runtime and find bugs like stack overflow or out-of-bounds accesses.
|
||||
Implementing this stub into coreboot like "Undefined behavior sanitizer support"
|
||||
would help to ensure code quality and make the runtime code more robust.
|
||||
|
||||
### Requirements
|
||||
* knowledge in the coreboot build system and the concept of stages
|
||||
* the KASAN feature can be improved in a way so that the memory space needed
|
||||
during runtime is not on a fixed address provided during compile time but
|
||||
determined during runtime. For this to achieve a small patch to the GCC will
|
||||
be helpful. Therefore minor GCC knowledge would be beneficial.
|
||||
* Implementation can be initially done in QEMU and improved on different
|
||||
mainboards and platforms
|
||||
|
||||
### Mentors
|
||||
* Werner Zeh <werner.zeh@gmx.net>
|
||||
|
||||
## Port payloads to ARM, AArch64 or RISC-V
|
||||
While we have a rather big set of payloads for x86 based platforms, all other
|
||||
architectures are rather limited. Improve the situation by porting a payload
|
||||
to one of the platforms, for example GRUB2, U-Boot (the UI part), Tianocore,
|
||||
yabits, FILO, or Linux-as-Payload.
|
||||
|
||||
Since this is a bit of a catch-all idea, an application to GSoC should pick a
|
||||
combination of payload and architecture to support.
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Should know the general boot flow in coreboot
|
||||
* other knowledge: It helps to be familiar with the architecture you want to
|
||||
work on.
|
||||
* hardware requirements: Much of this can be done in QEMU or other emulators,
|
||||
but the ability to test on real hardware is a plus.
|
||||
|
||||
### Mentors
|
||||
* Simon Glass <sjg@chromium.org> for U-Boot payload projects
|
||||
|
||||
## Fully support building coreboot with the Clang compiler
|
||||
Most coreboot code is written in C, and it would be useful to support
|
||||
a second compiler suite in addition to gcc. Clang is another popular
|
||||
compiler suite and the build system generally supports building coreboot
|
||||
with it, but firmware is a rather special situation and we need to
|
||||
adjust coreboot and Clang some more to get usable binaries out of that
|
||||
combination.
|
||||
|
||||
The goal would be to get the emulation targets to boot reliably first,
|
||||
but also to support real hardware. If you don't have hardware around,
|
||||
you likely will find willing testers for devices they own and work from
|
||||
their bug reports.
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Have a general concept of the build system
|
||||
* Clang knowledge: It may be necessary to apply minor modifications to Clang
|
||||
itself, but at least there will be Clang-specific compiler options etc to
|
||||
adapt, so some idea how compilers work and how to modify their behavior is
|
||||
helpful.
|
||||
* hardware requirements: If you have your own hardware that is already
|
||||
supported by coreboot that can be a good test target, but you will debug
|
||||
other people's hardware, too.
|
||||
* debugging experience: It helps if you know how to get the most out of a bug
|
||||
report, generate theories, build patches to test them and figure out what's
|
||||
going on from the resulting logs.
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Extend Ghidra to support analysis of firmware images
|
||||
[Ghidra](https://ghidra-sre.org) is a recently released cross-platform
|
||||
disassembler and decompiler that is extensible through plugins. Make it
|
||||
useful for firmware related work: Automatically parse formats (eg. by
|
||||
integrating UEFITool, cbfstool, decompressors), automatically identify
|
||||
16/32/64bit code on x86/amd64, etc.
|
||||
|
||||
This has been done in 2019 with [some neat
|
||||
features](https://github.com/al3xtjames/ghidra-firmware-utils) being
|
||||
developed, but it may be possible to expand support for all kinds of firmware
|
||||
analyses.
|
||||
|
||||
## Learn hardware behavior from I/O and memory access logs
|
||||
[SerialICE](https://www.serialice.com) is a tool to trace the behavior of
|
||||
executable code like firmware images. One result of that is a long log file
|
||||
containing the accesses to hardware resources.
|
||||
|
||||
It would be useful to have a tool that assists a developer-analyst in deriving
|
||||
knowledge about hardware from such logs. This likely can't be entirely
|
||||
automatic, but a tool that finds patterns and can propagate them across the
|
||||
log (incrementially raising the log from plain I/O accesses to a high-level
|
||||
description of driver behavior) would be of great use.
|
||||
|
||||
This is a research-heavy project.
|
||||
|
||||
### Requirements
|
||||
* Driver knowledge: Somebody working on this should be familiar with
|
||||
how hardware works (eg. MMIO based register access, index/data port
|
||||
accesses) and how to read data sheets.
|
||||
* Machine Learning: ML techniques may be useful to find structure in traces.
|
||||
|
||||
### Mentors
|
||||
* Ron Minnich <rminnich@google.com>
|
||||
|
||||
## Libpayload based memtest payload
|
||||
[Memtest86+](https://www.memtest.org/) has some limitations: first and
|
||||
foremost it only works on x86, while it can print to serial console the
|
||||
GUI only works in legacy VGA mode.
|
||||
|
||||
This project would involve porting the memtest suite to libpayload and
|
||||
build a payload around it.
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Should know how to build coreboot images and
|
||||
include payloads.
|
||||
* other knowledge: Knowledge on how dram works is a plus.
|
||||
* hardware requirements: Initial work can happen on qemu targets,
|
||||
being able to test on coreboot supported hardware is a plus.
|
||||
|
||||
### Mentors
|
||||
* TODO
|
||||
|
||||
## Fix POST code handling
|
||||
coreboot supports writing POST codes to I/O port 80.
|
||||
There are various Kconfigs that deal with POST codes, which don't have
|
||||
effect on most platforms.
|
||||
The code to send POST codes is scattered in C and Assembly, some use
|
||||
functions, some use macros and others simply use the `outb` instruction.
|
||||
The POST codes are duplicated between stages and aren't documented properly.
|
||||
|
||||
|
||||
Tasks:
|
||||
* Guard Kconfigs with a *depends on* to only show on supported platforms
|
||||
* Remove duplicated Kconfigs
|
||||
* Replace `outb(0x80, ...)` with calls to `post_code(...)`
|
||||
* Update Documentation/POSTCODES
|
||||
* Use defines from console/post_codes.h where possible
|
||||
* Drop duplicated POST codes
|
||||
* Make use of all possible 255 values
|
||||
|
||||
### Requirements
|
||||
* knowledge in the coreboot build system and the concept of stages
|
||||
* other knowledge: Little experience with C and x86 Assembly
|
||||
* hardware requirements: Nothing special
|
||||
|
||||
### Mentors
|
||||
* Patrick Rudolph <patrick.rudolph@9elements.com>
|
||||
* Christian Walter <christian.walter@9elements.com>
|
||||
|
||||
## Board status replacement
|
||||
The [Board status page](https://coreboot.org/status/board-status.html) allows
|
||||
to see last working commit of a board. The page is generated by a cron job
|
||||
that runs on a huge git repository.
|
||||
|
||||
Build an open source replacement written in Golang using existing tools
|
||||
and libraries, consisting of a backend, a frontend and client side
|
||||
scripts. The backend should connect to an SQL database with can be
|
||||
controlled using a RESTful API. The RESTful API should have basic authentication
|
||||
for managment tasks and new board status uploads.
|
||||
|
||||
At least one older test result should be keept in the database.
|
||||
|
||||
The frontend should use established UI libraries or frameworks (for example
|
||||
Angular) to display the current board status, that is if it's working or not
|
||||
and some details provided with the last test. If a board isn't working the last
|
||||
working commit (if any) should be shown in addition to the broken one.
|
||||
|
||||
Provide a script/tool that allows to:
|
||||
1. Push mainboard details from coreboot master CI
|
||||
2. Push mainboard test results from authenticated users containing
|
||||
* working
|
||||
* commit hash
|
||||
* bootlog (if any)
|
||||
* dmesg (if it's booting)
|
||||
* timestamps (if it's booting)
|
||||
* coreboot config
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Non-technical, needed to perform requirements analysis
|
||||
* software knowledge: Golang, SQL for the backend, JS for the frontend
|
||||
|
||||
### Mentors
|
||||
* Patrick Rudolph <patrick.rudolph@9elements.com>
|
||||
* Christian Walter <christian.walter@9elements.com>
|
||||
1235
Documentation/core/Kconfig.md
Normal file
1235
Documentation/core/Kconfig.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,81 +0,0 @@
|
||||
# Distributions
|
||||
|
||||
coreboot doesn't provide binaries but provides a toolbox that others can use
|
||||
to build boot firmware for all kinds of purposes. These third-parties can be
|
||||
broadly separated in two groups: Those shipping coreboot on their hardware,
|
||||
and those providing after-market firmware to extend the usefulness of devices.
|
||||
|
||||
|
||||
## Hardware shipping with coreboot
|
||||
|
||||
### Purism
|
||||
|
||||
[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
|
||||
security; part of that effort is to minimize the amount of proprietary and/or
|
||||
binary code. Their laptops ship with a blob-free OS and coreboot firmware
|
||||
with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
|
||||
|
||||
### ChromeOS Devices
|
||||
|
||||
All ChromeOS devices ([Chromebooks](https://chromebookdb.com/), Chromeboxes,
|
||||
Chromebit, etc) released from 2012 onward use coreboot for their main system
|
||||
firmware. Additionally, starting with the 2013 Chromebook Pixel, the firmware
|
||||
running on the Embedded Controller (EC - a small microcontroller which provides
|
||||
functions like battery management, keyboard support, and sensor interfacing)
|
||||
is open source as well.
|
||||
|
||||
### Libretrend
|
||||
|
||||
[Libretrend](https://libretrend.com) sells the Librebox, a NUC-like PC which
|
||||
ships with coreboot firmware.
|
||||
|
||||
|
||||
### PC Engines APUs
|
||||
|
||||
[PC Engines](https://pcengines.ch) designs and sells embedded PC hardware that
|
||||
ships with coreboot and support upstream maintenance for the devices through a
|
||||
third party, [3mdeb](https://3mdeb.com). They provide current and tested
|
||||
firmware binaries on [GitHub](https://pcengines.github.io).
|
||||
|
||||
## 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.
|
||||
|
||||
### MrChromebox
|
||||
|
||||
[MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
|
||||
images for the vast majority of x86-based Chromebooks and Chromeboxes, using
|
||||
Tianocore as the payload to provide a modern UEFI bootloader. Why replace
|
||||
coreboot with coreboot? Mr Chromebox's images are built using upstream
|
||||
coreboot (vs Google's older, static tree/branch), include many features and
|
||||
fixes not found in the stock firmware, and offer much broader OS compatibility
|
||||
(i.e., they run Windows as well as Linux). They also offer updated CPU
|
||||
microcode, as well as firmware updates for the device's embedded controller
|
||||
(EC). This firmware "takes the training wheels off" your ChromeOS device :)
|
||||
|
||||
### Heads
|
||||
|
||||
[Heads](http://osresearch.net) is an open source custom firmware and OS
|
||||
configuration for laptops and servers that aims to provide slightly better
|
||||
physical security and protection for data on the system. Unlike
|
||||
[Tails](https://tails.boum.org/), which aims to be a stateless OS that leaves
|
||||
no trace on the computer of its presence, Heads is intended for the case where
|
||||
you need to store data and state on the computer.
|
||||
|
||||
Heads is not just another Linux distribution – it combines physical hardening
|
||||
of specific hardware platforms and flash security features with custom coreboot
|
||||
firmware and a Linux boot loader in ROM.
|
||||
|
||||
### Skulls
|
||||
|
||||
[Skulls](https://github.com/merge/skulls) provides firmware images for
|
||||
laptops like the Lenovo Thinkpad X230. It uses upstream coreboot, an easy
|
||||
to use payload like SeaBIOS and Intel's latest microcode update.
|
||||
|
||||
It simplifies installation and includes compact documentation. Skulls also
|
||||
enables easy switching to [Heads](#heads) and back.
|
||||
@@ -1,313 +0,0 @@
|
||||
# Intel DPTF implementations in coreboot
|
||||
|
||||
## Introduction
|
||||
|
||||
Intel Dynamic Platform and Thermal Framework is a framework that can be used to
|
||||
help regulate the thermal properties (i.e., temperature) of an Intel-based
|
||||
computer. It does this by allowing the system designer to specify the different
|
||||
components that can generate heat, and/or dissipate heat. Under DPTF, the
|
||||
different components are referred to as `participants`. The different types of
|
||||
functionality available in DPTF are specified in terms of different `policies`.
|
||||
|
||||
## Components ("Participants")
|
||||
|
||||
The participants that can be involved in the current implementation are:
|
||||
- CPU (monolithic from a DPTF point-of-view)
|
||||
- Note that the CPU's internal temperature sensor is used here
|
||||
- 1 fan
|
||||
- Up to 4 temperature sensors (TSRs)
|
||||
- Battery charger
|
||||
|
||||
## Policies
|
||||
|
||||
In the current implementation, there are 3 different policies available:
|
||||
|
||||
### Passive Policy
|
||||
|
||||
The purpose of this policy is to monitor participant temperatures and is capable
|
||||
of controlling performance and throttling available on platform devices in order
|
||||
to regulate the temperatures of each participant. The temperature threshold
|
||||
points are defined by a `_PSV` ACPI object within each participant.
|
||||
|
||||
### Critical Policy
|
||||
|
||||
The Critical Policy is used for gracefully suspending or powering off the system
|
||||
when the temperature of participants exceeds critical threshold
|
||||
temperatures. Suspend is effected by specifying temperatures in a `_CRT` object
|
||||
for a participant, and poweroff is effected by specifying a temperature
|
||||
threshold in a `_HOT` ACPI object.
|
||||
|
||||
### Active Policy
|
||||
|
||||
This policy monitors the temperature of participants and controls fans to spin
|
||||
at varying speeds. These speeds are defined by the platform, and will be enabled
|
||||
depending on the various temperatures reported by participants.
|
||||
|
||||
# Note about units
|
||||
|
||||
ACPI uses unusual units for specifying various physical measurements. For
|
||||
example, temperatures are specified in 10ths of a degree K, and time is measured
|
||||
in tenths of a second. Those oddities are abstracted away in the DPTF library,
|
||||
by using degrees C for temperature, milliseconds for time, mW for power, and mA
|
||||
for current.
|
||||
|
||||
## Differences from the static ASL files (soc/intel/common/acpi/dptf/*.asl)
|
||||
|
||||
1) TCPU had many redundant methods. The many references to \_SB.CP00._* are not
|
||||
created anymore in recent SoCs and the ACPI spec says these are optional objects
|
||||
anyway. The defaults that were returned by these methods were redundant (all
|
||||
data was a 0). The following Methods were removed:
|
||||
|
||||
* _TSS
|
||||
* _TPC
|
||||
* _PTC
|
||||
* _TSD
|
||||
* _TDL
|
||||
* _PSS
|
||||
* _PDL
|
||||
|
||||
2) There is no more implicit inclusion of _ACn methods for TCPU (these must be
|
||||
specified in the devicetree entries or by calling the DPTF acpigen API).
|
||||
|
||||
# ACPI Tables
|
||||
|
||||
DPTF relies on an assortment of ACPI tables to provide parameters to the DPTF
|
||||
application. We will discuss the more important ones here.
|
||||
|
||||
1) _TRT - Thermal Relationship Table
|
||||
|
||||
This table is used when the Passive Policy is enabled, and is used to represent
|
||||
the thermal relationships in the system that can be controlled passively (i.e.,
|
||||
by throttling participants). A passive policy is defined by a Source (which
|
||||
generates heat), a Target (typically a temperature sensor), a Sampling Period
|
||||
(how often to check the temperature), an activation temperature threshold (for
|
||||
when to begin throttling), and a relative priority.
|
||||
|
||||
2) _ART - Active Relationship Table
|
||||
|
||||
This table is used when the Active Policy is enabled, and is used to represent
|
||||
active cooling relationships (i.e., which TSRs the fan can cool). An active
|
||||
policy contains a Target (the device the fan can cool), a Weight to control
|
||||
which participant needs more attention than others, and a list of temperature /
|
||||
fan percentage pairs. The list of pairs defines the fan control percentage that
|
||||
should be applied when the TSR reaches each successive threshold (_AC0 is the
|
||||
highest threshold, and represents the highest fan control percentage).
|
||||
|
||||
3) PPCC - Participant Power Control Capabilities
|
||||
|
||||
This table is used to describe parameters for controlling the SoC's Running
|
||||
Average Power Limits (RAPL, see below).
|
||||
|
||||
4) _FPS - Fan Performance States
|
||||
|
||||
This table describes the various fan speeds available for DPTF to use, along with
|
||||
various informational properties.
|
||||
|
||||
5) PPSS - Participant Performance Supported States
|
||||
|
||||
This table describes performance states supported by a participant (typically
|
||||
the battery charger).
|
||||
|
||||
# ACPI Methods
|
||||
|
||||
The Active and Passive policies also provide for short Methods to define
|
||||
different kinds of temperature thresholds.
|
||||
|
||||
1) _AC0, _AC1, _AC2, _AC3, ..., _AC9
|
||||
|
||||
These Methods can provide up to 10 temperature thresholds. What these do is set
|
||||
temperatures which act as the thresholds to active rows (fan speeds) in the
|
||||
ART. _AC0 is intended to be the highest temperature thresholds, and the lowest
|
||||
one can be any of them; leave the rest defined as 0 and they will be omitted
|
||||
from the output.
|
||||
|
||||
These are optional and are enabled by selecting the Active Policy.
|
||||
|
||||
2) _PSV
|
||||
|
||||
_PSV is a temperature threshold that is used to indicate to DPTF that it should
|
||||
begin taking passive measures (i.e., throttling of the Source) in order to
|
||||
reduce the temperature of the Target in question. It will check on the
|
||||
temperature according to the given sampling period.
|
||||
|
||||
This is optional and is enabled by selecting the Passive Policy.
|
||||
|
||||
3) _CRT and _HOT
|
||||
|
||||
When the temperature of the Source reaches the threshold specified in _CRT, then
|
||||
the system is supposed to execute a "graceful suspend". Similarly, when the Source
|
||||
reaches the temperature specified in _HOT, then the system is supposed to execute
|
||||
a "graceful shutdown".
|
||||
|
||||
These are optional, and are enabled by selecting the Critical Policy.
|
||||
|
||||
# How to use the devicetree entries
|
||||
|
||||
The `drivers/intel/dptf` chip driver is organized into several sections:
|
||||
- Policies
|
||||
- Controls
|
||||
- Options
|
||||
|
||||
The Policies section (`policies.active`, `policies.passive`, and
|
||||
`policies.critical`) is where the components of each policy are defined.
|
||||
|
||||
## Active Policy
|
||||
|
||||
Each Active Policy is defined in terms of 4 parts:
|
||||
1) A Source (this is implicitly defined as TFN1, the system fan)
|
||||
2) A Target (this is the device that can be affected by the policy, i.e.,
|
||||
this is a device that can be cooled by the fan)
|
||||
3) A 'Weight', which is defined as the Source's contribution to the Target's
|
||||
cooling capability (as a percentage, 0-100, often just left at 100).
|
||||
4) A list of temperature-fan percentage pairs, which define temperature
|
||||
thresholds that, when the Target reaches, the fan is defined to spin
|
||||
at the corresponding percentage of full duty cycle.
|
||||
|
||||
An example definition in the devicetree:
|
||||
```C
|
||||
register "policies.active[0]" = "{
|
||||
.target=DPTF_CPU,
|
||||
.weight=100,
|
||||
.thresholds={TEMP_PCT(85, 90),
|
||||
TEMP_PCT(80, 69),
|
||||
TEMP_PCT(75, 56),
|
||||
TEMP_PCT(70, 46),
|
||||
TEMP_PCT(65, 36),}}"
|
||||
```
|
||||
|
||||
This example sets up a policy wherein the CPU temperature sensor can be cooled
|
||||
by the fan. The 'weight' of this policy is 100% (this policy contributes 100% of
|
||||
the CPU's active cooling capability). When the CPU temperature first crosses
|
||||
65C, the fan is defined to spin at 36% of its duty cycle, and so forth up the
|
||||
rest of the table (note that it *must* be defined from highest temperature/
|
||||
percentage on down to the lowest).
|
||||
|
||||
## Passive Policy
|
||||
|
||||
Each Passive Policy is defined in terms of 5 parts:
|
||||
1) Source - The device that can be throttled
|
||||
2) Target - The device that controls the amount of throttling
|
||||
3) Period - How often to check the temperature of the Target
|
||||
4) Trip point - What temperature threshold to start throttling
|
||||
5) Priority - A number indicating the relative priority between different
|
||||
Policies
|
||||
|
||||
An example definition in the devicetree:
|
||||
```C
|
||||
register "policies.passive[0]" = "DPTF_PASSIVE(CHARGER, TEMP_SENSOR_1, 65, 60000)"
|
||||
```
|
||||
|
||||
This example sets up a policy to begin throttling the charger performance when
|
||||
temperature sensor 1 reaches 65C. The sampling period here is 60000 ms (60 s).
|
||||
The Priority is defaulted to 100 in this case.
|
||||
|
||||
## Critical Policy
|
||||
|
||||
Each Critical Policy is defined in terms of 3 parts:
|
||||
1) Source - A device that can trigger a critical event
|
||||
2) Type - What type of critical event to trigger (S4-entry or shutdown)
|
||||
3) Temperature - The temperature threshold that will cause the entry into S4 or
|
||||
to shutdown the system.
|
||||
|
||||
An example definition in the devicetree:
|
||||
|
||||
```C
|
||||
register "policies.critical[1]" = "DPTF_CRITICAL(CPU, 75, SHUTDOWN)"
|
||||
```
|
||||
|
||||
This example sets up a policy wherein ACPI will cause the system to shutdown
|
||||
(in a "graceful" manner) when the CPU temperature reaches 75C.
|
||||
|
||||
## Power Limits
|
||||
|
||||
Control over the SoC's Running Average Power Limits (RAPL) is one of the tools
|
||||
that DPTF uses to enact Passive policies. DPTF can control both PL1 and PL2, if
|
||||
the PPCC table is provided for the TCPU object. Each power limit is given the
|
||||
following options:
|
||||
1) Minimum power (in mW)
|
||||
2) Maximum power (in mW)
|
||||
3) Minimum time window (in ms)
|
||||
4) Maximum time window (in ms)
|
||||
5) Granularity, or minimum step size to control limits (in mW)
|
||||
|
||||
An example:
|
||||
```C
|
||||
register "controls.power_limits.pl1" = "{
|
||||
.min_power = 3000,
|
||||
.max_power = 15000,
|
||||
.time_window_min = 28 * MSECS_PER_SEC,
|
||||
.time_window_max = 32 * MSECS_PER_SEC,
|
||||
.granularity = 200,}"
|
||||
```
|
||||
|
||||
This example allow DPTF to control the SoC's PL1 level to between 3W and 15W,
|
||||
over a time interval ranging from 28 to 32 seconds, and it can move PL1 in
|
||||
increments of 200 mW.
|
||||
|
||||
## Charger Performance
|
||||
|
||||
The battery charger can be a large contributor of unwanted heat in a system that
|
||||
has one. Controlling the rate of charging is another tool that DPTF uses to enact
|
||||
Passive Policies. Each entry in the PPSS table consists of:
|
||||
1) A 'Control' value - an opaque value that the platform firmware uses
|
||||
to initiate a transition to the specified performance state. DPTF will call an
|
||||
ACPI method called `TCHG.SPPC` (Set Participant Performance Capability) if
|
||||
applicable, and will pass this opaque control value as its argument.
|
||||
2) The intended charging rate (in mA).
|
||||
|
||||
Example:
|
||||
```C
|
||||
register "controls.charger_perf[0]" = "{ 255, 1700 }"
|
||||
register "controls.charger_perf[1]" = "{ 24, 1500 }"
|
||||
register "controls.charger_perf[2]" = "{ 16, 1000 }"
|
||||
register "controls.charger_perf[3]" = "{ 8, 500 }"
|
||||
```
|
||||
|
||||
In this example, when DPTF decides to throttle the charger, it has four different
|
||||
performance states to choose from.
|
||||
|
||||
## Fan Performance
|
||||
|
||||
When using DPTF, the system fan (`TFN1`) is the device responsible for actively
|
||||
cooling the other temperature sensors on the mainboard. A fan speed table can be
|
||||
provided to DPTF to assist with fan control. Each entry holds the following:
|
||||
1) Percentage of full duty to spin the fan at
|
||||
2) Speed - Speed of the fan at that percentage; informational only, but given in
|
||||
RPM
|
||||
3) Noise - Amount of noise created by the fan at that percentage; informational
|
||||
only, but given in tenths of a decibel (centibel).
|
||||
4) Power - Amount of power consumed by the fan at that percentage; informational
|
||||
only, but given in mA.
|
||||
|
||||
Example:
|
||||
```C
|
||||
register "controls.fan_perf[0]" = "{ 90, 6700, 220, 2200, }"
|
||||
register "controls.fan_perf[1]" = "{ 80, 5800, 180, 1800, }"
|
||||
register "controls.fan_perf[2]" = "{ 70, 5000, 145, 1450, }"
|
||||
register "controls.fan_perf[3]" = "{ 60, 4900, 115, 1150, }"
|
||||
register "controls.fan_perf[4]" = "{ 50, 3838, 90, 900, }"
|
||||
register "controls.fan_perf[5]" = "{ 40, 2904, 55, 550, }"
|
||||
register "controls.fan_perf[6]" = "{ 30, 2337, 30, 300, }"
|
||||
register "controls.fan_perf[7]" = "{ 20, 1608, 15, 150, }"
|
||||
register "controls.fan_perf[8]" = "{ 10, 800, 10, 100, }"
|
||||
register "controls.fan_perf[9]" = "{ 0, 0, 0, 50, }"
|
||||
```
|
||||
|
||||
In this example, the fan has 10 different performance states, each in an even
|
||||
increment of 10 percentage points. This is common when specifying fine-grained
|
||||
control of the fan, wherein DPTF will interpolate between the percentages in the
|
||||
table for a given temperature threshold.
|
||||
|
||||
## Options
|
||||
|
||||
### Fan
|
||||
1) Fine-grained control - a boolean (see Fan Performance section above)
|
||||
2) Step-size - Recommended minimum step size (in percentage points) to adjust
|
||||
the fan speed when using fine-grained control (ranges from 1 - 9).
|
||||
3) Low-speed notify - If true, the platform will issue a `Notify (0x80)` to the
|
||||
fan device if a low fan speed is detected.
|
||||
|
||||
### Temperature sensors
|
||||
1) Hysteresis - The amount of hysteresis implemented in either circuitry or
|
||||
the firmware that reads the temperature sensor (in degrees C).
|
||||
2) Name - This name is applied to the _STR property of the sensor
|
||||
@@ -1,10 +0,0 @@
|
||||
# Platform independent drivers documentation
|
||||
|
||||
The drivers can be found in `src/drivers`. They are intended for onboard
|
||||
and plugin devices, significantly reducing integration complexity and
|
||||
they allow to easily reuse existing code accross platforms.
|
||||
|
||||
* [IPMI KCS](ipmi_kcs.md)
|
||||
* [SMMSTORE](smmstore.md)
|
||||
* [SoundWire](soundwire.md)
|
||||
* [SMMSTOREv2](smmstorev2.md)
|
||||
@@ -1,47 +0,0 @@
|
||||
# IPMI KCS driver
|
||||
|
||||
The driver can be found in `src/drivers/ipmi/`. It works with BMC that provide
|
||||
a KCS I/O interface as specified in the [IPMI] standard.
|
||||
|
||||
The driver detects the IPMI version, reserves the I/O space in coreboot's
|
||||
resource allocator and writes the required ACPI and SMBIOS tables.
|
||||
|
||||
## For developers
|
||||
|
||||
To use the driver, select the `IPMI_KCS` Kconfig and add the following PNP
|
||||
device under the LPC bridge device (in example for the KCS at 0xca2):
|
||||
|
||||
```
|
||||
chip drivers/ipmi
|
||||
device pnp ca2.0 on end # IPMI KCS
|
||||
end
|
||||
```
|
||||
|
||||
**Note:** The I/O base address needs to be aligned to 2.
|
||||
|
||||
The following registers can be set:
|
||||
|
||||
* `have_nv_storage`
|
||||
* Boolean
|
||||
* If true `nv_storage_device_address` will be added to SMBIOS type 38.
|
||||
* `nv_storage_device_address`
|
||||
* Integer
|
||||
* The NV storage address as defined in SMBIOS spec for type 38.
|
||||
* `bmc_i2c_address`
|
||||
* Integer
|
||||
* The i2c address of the BMC. zero if not applicable.
|
||||
* `have_apic`
|
||||
* Boolean
|
||||
* If true the `apic_interrupt` will be added to SPMI table.
|
||||
* `apic_interrupt`
|
||||
* Integer
|
||||
* The APIC interrupt used to notify about a change on the KCS.
|
||||
* `have_gpe`
|
||||
* Boolean
|
||||
* If true the `gpe_interrupt` will be added to SPMI table.
|
||||
* `gpe_interrupt`
|
||||
* Integer
|
||||
* The bit in GPE (SCI) used to notify about a change on the KCS.
|
||||
|
||||
|
||||
[IPMI]: https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf
|
||||
@@ -1,40 +0,0 @@
|
||||
# USB4 Retimers
|
||||
|
||||
# Introduction
|
||||
As USB speeds continue to increase (up to 5G, 10G, and even 20G or higher in
|
||||
newer revisions of the spec), it becomes more difficult to maintain signal
|
||||
integrity for longer traces. Devices such as retimers and redrivers can be used
|
||||
to help signals maintain their integrity over long distances.
|
||||
|
||||
A redriver is a device that boosts the high-frequency content of a signal in
|
||||
order to compensate for the attenuation typically caused by travelling through
|
||||
various circuit components (PCB, connectors, CPU, etc.). Redrivers are not
|
||||
protocol-aware, which makes them relatively simple. However, their effectiveness
|
||||
is limited, and may not work at all in some scenarios.
|
||||
|
||||
A retimer is a device that retransmits a fresh copy of the signal it receives,
|
||||
by doing CDR and retransmitting the data (i.e., it is protocol-aware). Since
|
||||
this is a digital component, it may have firmware.
|
||||
|
||||
|
||||
# Driver Usage
|
||||
|
||||
Some operating systems may have the ability to update firmware on USB4 retimers,
|
||||
and ultimately will need some way to power the device on and off so that its new
|
||||
firmware can be loaded. This is achieved by providing a GPIO signal that can be
|
||||
used for this purpose; its active state must be the one in which power is
|
||||
applied to the retimer. This driver will generate the required ACPI AML code
|
||||
which will toggle the GPIO in response to the kernel's request (through the
|
||||
`_DSM` ACPI method). Simply put something like the following in your devicetree:
|
||||
|
||||
```
|
||||
device pci 0.0 on
|
||||
chip drivers/intel/usb4/retimer
|
||||
register "power_gpio" = "ACPI_GPIO_OUTPUT_ACTIVE_HIGH(GPP_A0)"
|
||||
device generic 0 on end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
replacing the GPIO with the appropriate pin and polarity.
|
||||
|
||||
@@ -1,134 +0,0 @@
|
||||
# SMM based flash storage driver
|
||||
|
||||
This documents the API exposed by the x86 system management based
|
||||
storage driver.
|
||||
|
||||
## SMMSTORE
|
||||
|
||||
SMMSTORE is a [SMM] mediated driver to read from, write to and erase a
|
||||
predefined region in flash. It can be enabled by setting
|
||||
`CONFIG_SMMSTORE=y` in menuconfig.
|
||||
|
||||
This can be used by the OS or the payload to implement persistent
|
||||
storage to hold for instance configuration data, without needing
|
||||
to implement a (platform specific) storage driver in the payload
|
||||
itself.
|
||||
|
||||
The API provides append-only semantics for key/value pairs.
|
||||
|
||||
## API
|
||||
|
||||
### Storage region
|
||||
|
||||
By default SMMSTORE will operate on a separate FMAP region called
|
||||
`SMMSTORE`. The default generated FMAP will include such a region.
|
||||
On systems with a locked FMAP, e.g. in an existing vboot setup
|
||||
with a locked RO region, the option exists to add a cbfsfile
|
||||
called `smm_store` in the `RW_LEGACY` (if CHROMEOS) or in the
|
||||
`COREBOOT` FMAP regions. It is recommended for new builds using
|
||||
a handcrafted FMD that intend to make use of SMMSTORE to include a
|
||||
sufficiently large `SMMSTORE` FMAP region. It is recommended to
|
||||
align the `SMMSTORE` region to 64KiB for the largest flash erase
|
||||
op compatibility.
|
||||
|
||||
When a default generated FMAP is used the size of the FMAP region
|
||||
is equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least
|
||||
64KiB. Given that the current implementation lacks a way to rewrite
|
||||
key-value pairs at least a multiple of this is recommended.
|
||||
|
||||
### generating the SMI
|
||||
|
||||
SMMSTORE is called via an SMI, which is generated via a write to the
|
||||
IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
|
||||
contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
|
||||
port. `%ah` contains the SMMSTORE command. `%ebx` contains the
|
||||
parameter buffer to the SMMSTORE command.
|
||||
|
||||
### Return values
|
||||
|
||||
If a command succeeds, SMMSTORE will return with
|
||||
`SMMSTORE_RET_SUCCESS=0` on `%eax`. On failure SMMSTORE will return
|
||||
`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
|
||||
`SMMSTORE_REG_UNSUPPORTED=2` is returned.
|
||||
|
||||
**NOTE1**: The caller **must** check the return value and should make
|
||||
no assumption on the returned data if `%eax` does not contain
|
||||
`SMMSTORE_RET_SUCCESS`.
|
||||
|
||||
**NOTE2**: If the SMI returns without changing `%ax` assume that the
|
||||
SMMSTORE feature is not installed.
|
||||
|
||||
### Calling arguments
|
||||
|
||||
SMMSTORE supports 3 subcommands that are passed via `%ah`, the additional
|
||||
calling arguments are passed via `%ebx`.
|
||||
|
||||
**NOTE**: The size of the struct entries are in the native word size of
|
||||
smihandler. This means 32 bits in almost all cases.
|
||||
|
||||
|
||||
#### - SMMSTORE_CMD_CLEAR = 1
|
||||
|
||||
This clears the `SMMSTORE` storage region. The argument in `%ebx` is
|
||||
unused.
|
||||
|
||||
#### - SMMSTORE_CMD_READ = 2
|
||||
|
||||
The additional parameter buffer `%ebx` contains a pointer to
|
||||
the following struct:
|
||||
|
||||
```C
|
||||
struct smmstore_params_read {
|
||||
void *buf;
|
||||
ssize_t bufsize;
|
||||
};
|
||||
```
|
||||
|
||||
INPUT:
|
||||
- `buf`: is a pointer to where the data needs to be read
|
||||
- `bufsize`: is the size of the buffer
|
||||
|
||||
OUTPUT:
|
||||
- `buf`
|
||||
- `bufsize`: returns the amount of data that has actually been read.
|
||||
|
||||
#### - SMMSTORE_CMD_APPEND = 3
|
||||
|
||||
SMMSTORE takes a key-value approach to appending data. key-value pairs
|
||||
are never updated, they are always appended. It is up to the caller to
|
||||
walk through the key-value pairs after reading SMMSTORE to find the
|
||||
latest one.
|
||||
|
||||
The additional parameter buffer `%ebx` contains a pointer to
|
||||
the following struct:
|
||||
|
||||
```C
|
||||
struct smmstore_params_append {
|
||||
void *key;
|
||||
size_t keysize;
|
||||
void *val;
|
||||
size_t valsize;
|
||||
};
|
||||
```
|
||||
|
||||
INPUT:
|
||||
- `key`: pointer to the key data
|
||||
- `keysize`: size of the key data
|
||||
- `val`: pointer to the value data
|
||||
- `valsize`: size of the value data
|
||||
|
||||
#### Security
|
||||
|
||||
Pointers provided by the payload or OS are checked to not overlap with the SMM.
|
||||
That protects the SMM handler from being manipulated.
|
||||
|
||||
*However there's no validation done on the source or destination pointing to
|
||||
DRAM. A malicious application that is able to issue SMIs could extract arbitrary
|
||||
data or modify the currently running kernel.*
|
||||
|
||||
## External links
|
||||
|
||||
* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with 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
|
||||
@@ -1,221 +0,0 @@
|
||||
# SMM based flash storage driver Version 2
|
||||
|
||||
This documents the API exposed by the x86 system management based
|
||||
storage driver.
|
||||
|
||||
## SMMSTOREv2
|
||||
|
||||
SMMSTOREv2 is a [SMM] mediated driver to read from, write to and erase
|
||||
a predefined region in flash. It can be enabled by setting
|
||||
`CONFIG_SMMSTORE=y` and `CONFIG_SMMSTORE_V2=y` in menuconfig.
|
||||
|
||||
This can be used by the OS or the payload to implement persistent
|
||||
storage to hold for instance configuration data, without needing to
|
||||
implement a (platform specific) storage driver in the payload itself.
|
||||
|
||||
### Storage size and alignment
|
||||
|
||||
SMMSTORE version 2 requires a minimum alignment of 64 KiB, which should
|
||||
be supported by all flash chips. Not having to perform read-modify-write
|
||||
operations is desired, as it reduces complexity and potential for bugs.
|
||||
|
||||
This can be used by a FTW (FaultTolerantWrite) implementation that uses
|
||||
at least two regions in an A/B update scheme. The FTW implementation in
|
||||
EDK2 uses three different regions in the store:
|
||||
|
||||
- The variable store
|
||||
- The FTW spare block
|
||||
- The FTW working block
|
||||
|
||||
All regions must be block-aligned, and the FTW spare size must be larger
|
||||
than that of the variable store. FTW working block can be much smaller.
|
||||
With 64 KiB as block size, the minimum size of the FTW-enabled store is:
|
||||
|
||||
- The variable store: 1 block = 64 KiB
|
||||
- The FTW spare block: 2 blocks = 2 * 64 KiB
|
||||
- The FTW working block: 1 block = 64 KiB
|
||||
|
||||
Therefore, the minimum size for EDK2 FTW is 4 blocks, or 256 KiB.
|
||||
|
||||
## API
|
||||
|
||||
The API provides read and write access to an unformatted block storage.
|
||||
|
||||
### Storage region
|
||||
|
||||
By default SMMSTOREv2 will operate on a separate FMAP region called
|
||||
`SMMSTORE`. The default generated FMAP will include such a region. On
|
||||
systems with a locked FMAP, e.g. in an existing vboot setup with a
|
||||
locked RO region, the option exists to add a cbfsfile called `smm_store`
|
||||
in the `RW_LEGACY` (if CHROMEOS) or in the `COREBOOT` FMAP regions. It
|
||||
is recommended for new builds using a handcrafted FMD that intend to
|
||||
make use of SMMSTORE to include a sufficiently large `SMMSTORE` FMAP
|
||||
region. It is mandatory to align the `SMMSTORE` region to 64KiB for
|
||||
compatibility with the largest flash erase operation.
|
||||
|
||||
When a default generated FMAP is used, the size of the FMAP region is
|
||||
equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least 64 KiB.
|
||||
To support a fault tolerant write mechanism, at least a multiple of
|
||||
this size is recommended.
|
||||
|
||||
### Communication buffer
|
||||
|
||||
To prevent malicious ring0 code to access arbitrary memory locations,
|
||||
SMMSTOREv2 uses a communication buffer in CBMEM/HOB for all transfers.
|
||||
This buffer has to be at least 64 KiB in size and must be installed
|
||||
before calling any of the SMMSTORE read or write operations. Usually,
|
||||
coreboot will install this buffer to transfer data between ring0 and
|
||||
the [SMM] handler.
|
||||
|
||||
In order to get the communication buffer address, the payload or OS
|
||||
has to read the coreboot table with tag `0x0039`, containing:
|
||||
|
||||
```C
|
||||
struct lb_smmstorev2 {
|
||||
uint32_t tag;
|
||||
uint32_t size;
|
||||
uint32_t num_blocks; /* Number of writeable blocks in SMM */
|
||||
uint32_t block_size; /* Size of a block in byte. Default: 64 KiB */
|
||||
uint32_t mmap_addr; /* MMIO address of the store for read only access */
|
||||
uint32_t com_buffer; /* Physical address of the communication buffer */
|
||||
uint32_t com_buffer_size; /* Size of the communication buffer in byte */
|
||||
uint8_t apm_cmd; /* The command byte to write to the APM I/O port */
|
||||
uint8_t unused[3]; /* Set to zero */
|
||||
};
|
||||
```
|
||||
|
||||
The absence of this coreboot table entry indicates that there's no
|
||||
SMMSTOREv2 support.
|
||||
|
||||
### Blocks
|
||||
|
||||
The SMMSTOREv2 splits the SMMSTORE FMAP partition into smaller chunks
|
||||
called *blocks*. Every block is at least the size of 64KiB to support
|
||||
arbitrary NOR flash erase ops. A payload or OS must make no further
|
||||
assumptions about the block or communication buffer size.
|
||||
|
||||
### Generating the SMI
|
||||
|
||||
SMMSTOREv2 is called via an SMI, which is generated via a write to the
|
||||
IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
|
||||
contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
|
||||
port. `%ah` contains the SMMSTOREv2 command. `%ebx` contains the
|
||||
parameter buffer to the SMMSTOREv2 command.
|
||||
|
||||
### Return values
|
||||
|
||||
If a command succeeds, SMMSTOREv2 will return with
|
||||
`SMMSTORE_RET_SUCCESS=0` in `%eax`. On failure SMMSTORE will return
|
||||
`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
|
||||
`SMMSTORE_REG_UNSUPPORTED=2` is returned.
|
||||
|
||||
**NOTE 1**: The caller **must** check the return value and should make
|
||||
no assumption on the returned data if `%eax` does not contain
|
||||
`SMMSTORE_RET_SUCCESS`.
|
||||
|
||||
**NOTE 2**: If the SMI returns without changing `%ax`, it can be assumed
|
||||
that the SMMSTOREv2 feature is not installed.
|
||||
|
||||
### Calling arguments
|
||||
|
||||
SMMSTOREv2 supports 3 subcommands that are passed via `%ah`, the
|
||||
additional calling arguments are passed via `%ebx`.
|
||||
|
||||
**NOTE**: The size of the struct entries are in the native word size of
|
||||
smihandler. This means 32 bits in almost all cases.
|
||||
|
||||
#### - SMMSTORE_CMD_INIT = 4
|
||||
|
||||
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
|
||||
|
||||
SMMSTOREv2 allows reading arbitrary data. It is up to the caller to
|
||||
initialize the store with meaningful data before using it.
|
||||
|
||||
The additional parameter buffer `%ebx` contains a pointer to the
|
||||
following struct:
|
||||
|
||||
```C
|
||||
struct smmstore_params_raw_read {
|
||||
uint32_t bufsize;
|
||||
uint32_t bufoffset;
|
||||
uint32_t block_id;
|
||||
} __packed;
|
||||
```
|
||||
|
||||
INPUT:
|
||||
- `bufsize`: Size of data to read within the communication buffer
|
||||
- `bufoffset`: Offset within the communication buffer
|
||||
- `block_id`: Block to read from
|
||||
|
||||
#### - SMMSTORE_CMD_RAW_WRITE = 6
|
||||
|
||||
SMMSTOREv2 allows writing arbitrary data. It is up to the caller to
|
||||
erase a block before writing it.
|
||||
|
||||
The additional parameter buffer `%ebx` contains a pointer to
|
||||
the following struct:
|
||||
|
||||
```C
|
||||
struct smmstore_params_raw_write {
|
||||
uint32_t bufsize;
|
||||
uint32_t bufoffset;
|
||||
uint32_t block_id;
|
||||
} __packed;
|
||||
```
|
||||
|
||||
INPUT:
|
||||
- `bufsize`: Size of data to write within the communication buffer
|
||||
- `bufoffset`: Offset within the communication buffer
|
||||
- `block_id`: Block to write to
|
||||
|
||||
#### - SMMSTORE_CMD_RAW_CLEAR = 7
|
||||
|
||||
SMMSTOREv2 allows clearing blocks. A cleared block will read as `0xff`.
|
||||
By providing multiple blocks the caller can implement a fault tolerant
|
||||
write mechanism. It is up to the caller to clear blocks before writing
|
||||
to them.
|
||||
|
||||
|
||||
```C
|
||||
struct smmstore_params_raw_clear {
|
||||
uint32_t block_id;
|
||||
} __packed;
|
||||
```
|
||||
|
||||
INPUT:
|
||||
- `block_id`: Block to erase
|
||||
|
||||
#### Security
|
||||
|
||||
Pointers provided by the payload or OS are checked to not overlap with
|
||||
SMM. This protects the SMM handler from being compromised.
|
||||
|
||||
As all information is exchanged using the communication buffer and
|
||||
coreboot tables, there's no risk that a malicious application capable
|
||||
of issuing SMIs could extract arbitrary data or modify the currently
|
||||
running kernel.
|
||||
|
||||
## External links
|
||||
|
||||
* [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
|
||||
@@ -1,496 +0,0 @@
|
||||
# SoundWire Implementation in coreboot
|
||||
|
||||
## Introduction
|
||||
|
||||
SoundWire is an audio interface specification from the MIPI Alliance.
|
||||
|
||||
- Low complexity
|
||||
- Low power
|
||||
- Low latency
|
||||
- Two pins (clock and data)
|
||||
- Multi-drop capable
|
||||
- Multiple audio streams
|
||||
- Embedded control/command channel
|
||||
|
||||
The main *SoundWire Specification* is at version 1.2 and can be downloaded from
|
||||
<https://mipi.org> but it is unfortunately only available to MIPI Alliance members.
|
||||
|
||||
There is a separate *SoundWire Discovery and Configuration (DisCo) Specification* which
|
||||
is at version 1.0 and is available for non-members after providing name and email at
|
||||
<https://resources.mipi.org/disco_soundwire>.
|
||||
|
||||
The coreboot implementation is based on the SoundWire DisCo Specification which defines
|
||||
object hierarchy and properties for providing topology and configuration information to
|
||||
OS kernel drivers via ACPI or DeviceTree.
|
||||
|
||||
SoundWire itself is architecture independent and the coreboot basic definition is also not
|
||||
specific to any to any SoC. The examples in this document use ACPI to generate properties,
|
||||
but the same structures and properties would be needed in a DeviceTree implementation.
|
||||
|
||||
## Bus
|
||||
|
||||
The SoundWire bus commonly consists of two pins:
|
||||
|
||||
* Clock: A common clock signal distributed from the master to all of the slaves.
|
||||
* Data: A shared data signal that can be driven by any of the devices, and has a defined
|
||||
value when no device is driving it.
|
||||
|
||||
While most designs have one data lane it is possible for a multi-lane device to have up
|
||||
to 8 data lanes and thus would have more than two pins.
|
||||
|
||||
A SoundWire bus consists of one master device, up to 11 slave devices, and an optional
|
||||
monitor interface for debug.
|
||||
|
||||
SoundWire is an enumerable bus, but not a discoverable one. That means it is required
|
||||
for firmware to provide details about the connected devices to the OS.
|
||||
|
||||
### Controller
|
||||
|
||||
A SoundWire controller contains one or more master devices. The handling of multiple
|
||||
masters is left up to the implementation, they may share a clock or be operated
|
||||
independently or entirely in tandem. The master devices connected to a controller are
|
||||
also referred to as links.
|
||||
|
||||
In coreboot the controller device is provided by the SoC or an add-in PCI card.
|
||||
|
||||
### Master
|
||||
|
||||
A SoundWire master (or link) device is responsible for clock and data handling, bus
|
||||
management, and bit slot allocation.
|
||||
|
||||
In coreboot the definition of the master device is left up to the controller and the
|
||||
mainboard should only need to know the controller's SoundWire topology (number of masters)
|
||||
to configure `devicetree.cb`.
|
||||
|
||||
It may however be expected to provide some additional SoC-specific configuration data to
|
||||
the controller, such as an input clock rate or a list of available masters that cannot
|
||||
be determined at run time.
|
||||
|
||||
### Slave
|
||||
|
||||
SoundWire slave devices are connected to a master and respond to the two-wire control
|
||||
information on the SoundWire bus. There can be up to 11 slave devices on a bus and they
|
||||
are capable of interrupting and waking the host.
|
||||
|
||||
Slave devices may also have master links which can be connected to other slave devices.
|
||||
It is also possible for a multi-lane slave device to have multiple data lanes connected
|
||||
to different combinations of master and slave devices.
|
||||
|
||||
In coreboot the slave device is defined by a codec driver which should be found in the
|
||||
source tree at `src/drivers/soundwire`.
|
||||
|
||||
The mainboard provides:
|
||||
|
||||
* Master link that this slave device is connected to.
|
||||
* Unique ID that this codec responds to on the SoundWire bus.
|
||||
* Multi-lane mapping. (optional)
|
||||
|
||||
The codec driver provides:
|
||||
|
||||
* Slave device properties.
|
||||
* Audio Mode properties including bus frequencies and sampling rates.
|
||||
* Data Port 1-14 properties such as word lengths, interrupt support, channels.
|
||||
* Data Port 0 and Bulk Register Access properties. (optional)
|
||||
|
||||
### Monitor
|
||||
|
||||
A SoundWire monitor device is defined that allows for test equipment to snoop the bus and
|
||||
take over and issue commands. The monitor interface is not defined for coreboot.
|
||||
|
||||
### Example SoundWire Bus
|
||||
|
||||
```
|
||||
+---------------+ +---------------+
|
||||
| | Clock Signal | |
|
||||
| Master |-------+-------------------------------| Slave |
|
||||
| Interface | | Data Signal | Interface 1 |
|
||||
| |-------|-------+-----------------------| |
|
||||
+---------------+ | | +---------------+
|
||||
| |
|
||||
| |
|
||||
| |
|
||||
+--+-------+--+
|
||||
| |
|
||||
| Slave |
|
||||
| Interface 2 |
|
||||
| |
|
||||
+-------------+
|
||||
```
|
||||
|
||||
## coreboot
|
||||
|
||||
The coreboot implementation of SoundWire integrates with the device model and takes
|
||||
advantage of the hierarchical nature of `devicetree.cb` to populate the topology.
|
||||
|
||||
The architecture-independent SoundWire tables are defined at
|
||||
|
||||
src/include/device/soundwire.h
|
||||
|
||||
Support for new devices comes in three forms:
|
||||
|
||||
1. New controller and master drivers. The first implementation in coreboot is for an Intel
|
||||
SoC but the SoundWire specification is in wide use on various ARM SoCs.
|
||||
|
||||
Controller drivers can be implemented in `src/soc` or `src/drivers` and should
|
||||
strive to re-use code as much as possible between different SoC generations from the
|
||||
same vendor.
|
||||
|
||||
2. New codec drivers. These should be implemented for each codec that is added which
|
||||
supports SoundWire. The properties vary between codecs and careful study of the data sheet
|
||||
is necessary to ensure proper operation.
|
||||
|
||||
Codec drivers should be implemented in `src/drivers/soundwire` as separate chip drivers.
|
||||
As every codec is different there may not be opportunities of code re-use except between
|
||||
similar codecs from the same vendor.
|
||||
|
||||
3. New mainboards with SoundWire support. The mainboard will combine controllers and codecs
|
||||
to form a topology that is described in `devicetree.cb`. Some devices may need to provide
|
||||
board-specific configuration information, and multi-lane devices will need to provide the
|
||||
master/slave lane map.
|
||||
|
||||
## ACPI Implementation
|
||||
|
||||
The implementation for x86 devices relies on ACPI for providing device properties to the OS
|
||||
kernel drivers.
|
||||
|
||||
The ACPI implementation can be found at
|
||||
|
||||
src/acpi/soundwire.c
|
||||
|
||||
And used by including
|
||||
|
||||
#include <acpi/acpi_soundwire.h>
|
||||
|
||||
### Controller
|
||||
|
||||
The controller driver should populate a `struct soundwire_controller`:
|
||||
|
||||
```c
|
||||
/**
|
||||
* struct soundwire_controller - SoundWire controller properties.
|
||||
* @master_count: Number of masters present on this device.
|
||||
* @master_list: One entry for each master device.
|
||||
*/
|
||||
struct soundwire_controller {
|
||||
unsigned int master_list_count;
|
||||
struct soundwire_link master_list[SOUNDWIRE_MAX_DEV];
|
||||
};
|
||||
```
|
||||
|
||||
Once the detail of the master links are specified in the `master_list` variable, the controller
|
||||
properties for the ACPI object can be generated:
|
||||
|
||||
```c
|
||||
struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
|
||||
soundwire_gen_controller(dsd, &soc_controller, NULL);
|
||||
acpi_dp_write(dsd);
|
||||
```
|
||||
|
||||
If the controller needs to generate custom properties for links it can provide a callback
|
||||
function to `soundwire_gen_controller()` instead of passing NULL:
|
||||
|
||||
```c
|
||||
static void controller_link_prop_cb(struct acpi_dp *dsd, unsigned int id,
|
||||
struct soundwire_controller *controller)
|
||||
{
|
||||
acpi_dp_add_integer(dsd, "custom-link-property", 1);
|
||||
}
|
||||
```
|
||||
|
||||
### Codec
|
||||
|
||||
The codec driver should populate a *struct soundwire_codec* with necessary properties:
|
||||
|
||||
```c
|
||||
/**
|
||||
* struct soundwire_codec - Contains all configuration for a SoundWire codec slave device.
|
||||
* @slave: Properties for slave device.
|
||||
* @audio_mode: Properties for Audio Mode for Data Ports 1-14.
|
||||
* @dpn: Properties for Data Ports 1-14.
|
||||
* @multilane: Properties for slave multilane device. (optional)
|
||||
* @dp0_bra_mode: Properties for Bulk Register Access mode for Data Port 0. (optional)
|
||||
* @dp0: Properties for Data Port 0 for Bulk Register Access. (optional)
|
||||
*/
|
||||
struct soundwire_codec {
|
||||
struct soundwire_slave *slave;
|
||||
struct soundwire_audio_mode *audio_mode[SOUNDWIRE_MAX_DEV];
|
||||
struct soundwire_dpn_entry dpn[SOUNDWIRE_MAX_DPN - SOUNDWIRE_MIN_DPN];
|
||||
struct soundwire_multilane *multilane;
|
||||
struct soundwire_bra_mode *dp0_bra_mode[SOUNDWIRE_MAX_DEV];
|
||||
struct soundwire_dp0 *dp0;
|
||||
};
|
||||
```
|
||||
|
||||
Many of these properties are optional, and depending on the codec will not be supported.
|
||||
|
||||
#### Slave Device Properties
|
||||
|
||||
These properties provide information about the codec device and what features it supports:
|
||||
|
||||
* Wake capability
|
||||
* Clock stop behavior
|
||||
* Clock and channel state machine behavior
|
||||
* Features like register pages, broadcast read, bank delay, and high performance PHY
|
||||
|
||||
#### Multi-lane Slave Device Properties
|
||||
|
||||
Most slave devices have a single data pin and a single lane, but it is possible for up to
|
||||
7 other lanes to be supported on a device. These lanes can be connected to other master
|
||||
links or to other slave devices.
|
||||
|
||||
If a codec supports this feature it must indicate that by providing an entry for
|
||||
`struct soundwire_multilane` in the chip configuration.
|
||||
|
||||
```c
|
||||
/**
|
||||
* struct drivers_soundwire_example_config - Example codec configuration.
|
||||
* @multilane: Multi-lane slave configuration.
|
||||
*/
|
||||
struct drivers_soundwire_example_config {
|
||||
struct soundwire_multilane multilane;
|
||||
};
|
||||
```
|
||||
|
||||
The mainboard is required to provide the lane map in `devicetree.cb` for any codec that has
|
||||
multiple lanes connected. This includes the definition up to 7 entries that indicate which
|
||||
lane number on the slave devices (array index starting at 1) maps to which other device:
|
||||
|
||||
```
|
||||
chip drivers/soundwire/multilane_codec
|
||||
register "multilane.lane_mapping" = "{
|
||||
{
|
||||
# Slave Lane 1 maps to Master Lane 2
|
||||
.lane = 1,
|
||||
.direction = MASTER_LANE,
|
||||
.connection.master_lane = 2
|
||||
},
|
||||
{
|
||||
# Slave Lane 3 maps to Slave Link B
|
||||
.lane = 3,
|
||||
.direction = SLAVE_LINK,
|
||||
.connection.slave_link = 1
|
||||
}
|
||||
}"
|
||||
device generic 0.0 on end
|
||||
end
|
||||
```
|
||||
|
||||
#### Data Port 0 Properties
|
||||
|
||||
SoundWire Data Port 0 (DP0) is a special port used for control and status operation relating
|
||||
to the whole device interface, and as a special data port for bulk read/write operations.
|
||||
|
||||
The properties for data port 0 are different from that of data ports 1-14 and are about the
|
||||
control channel behavior and the overall bulk register mode.
|
||||
|
||||
Data port 0 is not required to be supported by the slave device.
|
||||
|
||||
#### Bulk Register Access Mode Properties
|
||||
|
||||
Bulk Register Access (BRA) is an optional mechanism for transporting higher bandwidth of
|
||||
register operations than the typical command mechanism. The BRA protocol is a particular
|
||||
format of the data on the (optional) data port 0 connection between the master and slave.
|
||||
|
||||
The BRA protocol may have alignment or timing requirements that are directly related to the
|
||||
bus frequencies. As a result there may be several configurations listed, for symmetry with
|
||||
the audio modes paired with data ports 1-14.
|
||||
|
||||
#### Data Port 1-14 Properties
|
||||
|
||||
Data ports 1-14 are typically dedicated to streaming audio payloads, and each data port can
|
||||
have from 1 to 8 channels. There are different levels of data ports, with some registers
|
||||
being required and supported on all data ports and some optional registers only being used
|
||||
on some data ports.
|
||||
|
||||
Data ports can have both a sink and a source component, and the codec may support one or
|
||||
both of these on each port.
|
||||
|
||||
Similar to data port 0 the properties defined here describe the capabilities and supported
|
||||
features of each data port, and they may be configured separately. For example the Maxim
|
||||
MAX98373 codec supports a 32bit source data port for speaker output, and a 16bit sink data
|
||||
port for speaker sense data.
|
||||
|
||||
#### Audio Mode Properties
|
||||
|
||||
Each data port may be tied to one or more audio modes. The audio mode describes the actual
|
||||
audio capabilities of the codec, including supported frequencies and sample rates. These
|
||||
modes can be shared by multiple data ports and do not need to be duplicated.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
static struct soundwire_audio_mode audio_mode = {
|
||||
.bus_frequency_max = 24 * MHz,
|
||||
.bus_frequency_min = 24 * KHz,
|
||||
.max_sampling_frequency = 192 * KHz,
|
||||
.min_sampling_frequency = 8 * KHz,
|
||||
};
|
||||
static struct soundwire_dpn codec_dp1 = {
|
||||
[...]
|
||||
.port_audio_mode_count = 1,
|
||||
.port_audio_mode_list = {0}
|
||||
};
|
||||
static struct soundwire_dpn codec_dp3 = {
|
||||
[...]
|
||||
.port_audio_mode_count = 1,
|
||||
.port_audio_mode_list = {0}
|
||||
};
|
||||
```
|
||||
|
||||
### Generating Codec Properties
|
||||
|
||||
Once the properties are known it can generate the ACPI code with:
|
||||
|
||||
```c
|
||||
struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
|
||||
soundwire_gen_codec(dsd, &soundwire_codec, NULL);
|
||||
acpi_dp_write(dsd);
|
||||
```
|
||||
|
||||
If the codec needs to generate custom properties for links it can provide a callback
|
||||
function to `soundwire_gen_codec()` instead of passing NULL:
|
||||
|
||||
```c
|
||||
static void codec_dp_prop_cb(struct acpi_dp *dsd, unsigned int id,
|
||||
struct soundwire_codec *codec)
|
||||
{
|
||||
acpi_dp_add_integer(dsd, "custom-dp-property", 1);
|
||||
}
|
||||
```
|
||||
|
||||
#### Codec Address
|
||||
|
||||
SoundWire slave devices use a SoundWire defined ACPI _ADR that requires a 64-bit integer
|
||||
and uses the master link ID and slave device unique ID to form a unique address for the
|
||||
device on this controller.
|
||||
|
||||
SoundWire addresses must be distinguishable from all other slave devices on the same master
|
||||
link, so multiple instances of the same manufacturer and part on the same master link will
|
||||
need different unique IDs. The value is typically determined by strapping pins on the codec
|
||||
chip and can be decoded for this table with the codec datasheet and board schematics.
|
||||
|
||||
```c
|
||||
/**
|
||||
* struct soundwire_address - SoundWire ACPI Device Address Encoding.
|
||||
* @version: SoundWire specification version from &enum soundwire_version.
|
||||
* @link_id: Zero-based SoundWire Link Number.
|
||||
* @unique_id: Unique ID for multiple devices.
|
||||
* @manufacturer_id: Manufacturer ID from include/device/mipi_ids.h.
|
||||
* @part_id: Vendor defined part ID.
|
||||
* @class: MIPI class encoding in &enum mipi_class.
|
||||
*/
|
||||
struct soundwire_address {
|
||||
enum soundwire_version version;
|
||||
uint8_t link_id;
|
||||
uint8_t unique_id;
|
||||
uint16_t manufacturer_id;
|
||||
uint16_t part_id;
|
||||
enum mipi_class class;
|
||||
};
|
||||
```
|
||||
|
||||
This ACPI address can be generated by calling the provided acpigen function:
|
||||
|
||||
acpigen_write_ADR_soundwire_device(const struct soundwire_address *sdw);
|
||||
|
||||
### Mainboard
|
||||
|
||||
The mainboard needs to select appropriate drivers in `Kconfig` and define the topology in
|
||||
`devicetree.cb` with the controllers and codecs that exist on the board.
|
||||
|
||||
The topology uses the **generic** device to describe SoundWire:
|
||||
|
||||
```c
|
||||
struct generic_path {
|
||||
unsigned int id; /* SoundWire Master Link ID */
|
||||
unsigned int subid; /* SoundWire Slave Unique ID */
|
||||
};
|
||||
```
|
||||
|
||||
This allows devices to be specified in `devicetree.cb` with the necessary information to
|
||||
generate ACPI address and device properties.
|
||||
|
||||
```
|
||||
chip drivers/intel/soundwire
|
||||
# SoundWire Controller 0
|
||||
device generic 0 on
|
||||
chip drivers/soundwire/codec1
|
||||
# SoundWire Link 0 ID 0
|
||||
device generic 0.0 on end
|
||||
end
|
||||
chip drivers/soundwire/codec2
|
||||
# SoundWire Link 1 ID 2
|
||||
device generic 1.2 on end
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Volteer Example
|
||||
|
||||
This is an example of an Intel Tiger Lake reference board using SoundWire Link 0 for the
|
||||
headphone codec connection, and Link 1 for connecting two speaker amps for stereo speakers.
|
||||
|
||||
The mainboard can be found at
|
||||
|
||||
src/mainboard/google/volteer
|
||||
|
||||
```
|
||||
+------------------+ +-------------------+
|
||||
| | | Headphone Codec |
|
||||
| Intel Tiger Lake | +--->| Realtek ALC5682 |
|
||||
| SoundWire | | | ID 1 |
|
||||
| Controller | | +-------------------+
|
||||
| | |
|
||||
| Link 0 +----+ +-------------------+
|
||||
| | | Left Speaker Amp |
|
||||
| Link 1 +----+--->| Maxim MAX98373 |
|
||||
| | | | ID 3 |
|
||||
| Link 2 | | +-------------------+
|
||||
| | |
|
||||
| Link 3 | | +-------------------+
|
||||
| | | | Right Speaker Amp |
|
||||
+------------------+ +--->| Maxim MAX98373 |
|
||||
| ID 7 |
|
||||
+-------------------+
|
||||
```
|
||||
|
||||
This implementation requires a controller driver for the Intel Tigerlake SoC and a codec
|
||||
driver for the Realtek and Maxim chips. If those drivers did not already exist they would
|
||||
need to be added and reviewed separately before adding the support to the mainboard.
|
||||
|
||||
The volteer example requires some `Kconfig` options to be selected:
|
||||
|
||||
```
|
||||
config BOARD_GOOGLE_BASEBOARD_VOLTEER
|
||||
select DRIVERS_INTEL_SOUNDWIRE
|
||||
select DRIVERS_SOUNDWIRE_ALC5682
|
||||
select DRIVERS_SOUNDWIRE_MAX98373
|
||||
```
|
||||
|
||||
And the following `devicetree.cb` entries to define this topology:
|
||||
|
||||
```
|
||||
device pci 1f.3 on
|
||||
chip drivers/intel/soundwire
|
||||
# SoundWire Controller 0
|
||||
device generic 0 on
|
||||
chip drivers/soundwire/alc5682
|
||||
# SoundWire Link 0 ID 1
|
||||
register "desc" = ""Headphone Jack""
|
||||
device generic 0.1 on end
|
||||
end
|
||||
chip drivers/soundwire/max98373
|
||||
# SoundWire Link 0 ID 1
|
||||
register "desc" = ""Left Speaker Amp""
|
||||
device generic 1.3 on end
|
||||
end
|
||||
chip drivers/soundwire/max98373
|
||||
# SoundWire Link 1 ID 7
|
||||
register "desc" = ""Right Speaker Amp""
|
||||
device generic 1.7 on end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
@@ -1,28 +0,0 @@
|
||||
# Flashing firmware externally supplying direct power
|
||||
|
||||
**WARNING:** Never use a high current rated power supply, like PC ATX power
|
||||
supply. It'll literally melt your PCB traces on short circuit.
|
||||
|
||||
On some mainboards the flash IC Vcc pin is connected to a diode, which prevents
|
||||
powering the rest of the board.
|
||||
|
||||
![][flash_ic_diode]
|
||||
|
||||
Please have a look at the mainboard specific documentation for details.
|
||||
|
||||
On those boards it's safe to use a programmer and supply power externally.
|
||||
|
||||
**WARNING:** Verify that you apply the correct voltage!
|
||||
|
||||
## USB programmer
|
||||
USB programmers are usually current limited by the host USB hub. On USB 2.0
|
||||
ports the limit is 500mA, which is sufficient to power the flash. Those are
|
||||
the best choice as they are stateless and have a fast power on reset cycle.
|
||||
|
||||
## Single board computers (like BeagleBone Black / RPi)
|
||||
Be careful when connecting a flash chip, especially when using a Pomona
|
||||
test-clip. A short circuit or overcurrent (250mA) causes a brown-out reset,
|
||||
resulting in a reboot of the running operating system (and possible loss of
|
||||
remote shell).
|
||||
|
||||
[flash_ic_diode]: flash_ic_diode.svg
|
||||
@@ -1,23 +0,0 @@
|
||||
# Flashing firmware standalone
|
||||
|
||||
If none of the other methods work, there are three possibilities:
|
||||
|
||||
## Desolder
|
||||
You must remove or desolder the flash IC before you can flash it.
|
||||
It's recommended to solder a socket in place of the flash IC.
|
||||
|
||||
When flashing the IC, always connect all input pins.
|
||||
If in doubt, pull /WP, /HOLD, /RESET and alike up towards Vcc.
|
||||
|
||||
## SPI flash emulator
|
||||
If you are a developer, you might want to use an [EM100Pro] instead, which sets
|
||||
the onboard flash on hold, and allows to run custom firmware.
|
||||
It provides a very fast development cycle without actually writing to flash.
|
||||
|
||||
## SPI flash overwrite
|
||||
It is possible to set the onboard flash on hold and use another flash chip.
|
||||
Connect all lines one-to-one, except /HOLD. Pull /HOLD of the soldered flash IC
|
||||
low, and /HOLD of your replacement flash IC high.
|
||||
|
||||
|
||||
[EM100Pro]: https://www.dediprog.com/product/EM100Pro
|
||||
@@ -1,61 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
|
||||
<svg width="4cm" height="3cm" viewBox="311 435 68 45" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<g>
|
||||
<g>
|
||||
<rect style="fill: #ffffff" x="322.125" y="451.034" width="37.75" height="26.6444"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="322.125" y="451.034" width="37.75" height="26.6444"/>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="341" y="465.734">
|
||||
<tspan x="341" y="465.734"></tspan>
|
||||
</text>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.875" y1="456.784" x2="368.527" y2="456.784"/>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="348.75" y="457.909">
|
||||
<tspan x="348.75" y="457.909">VCC</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.763" y1="461.772" x2="368.652" y2="461.784"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.138" y1="466.872" x2="368.527" y2="466.909"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.277" y1="471.534" x2="368.402" y2="471.534"/>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="345.752" y="463.247">
|
||||
<tspan x="345.752" y="463.247">HOLD</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="346.652" y1="459.159" x2="358.402" y2="459.159"/>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="349.752" y="468.247">
|
||||
<tspan x="349.752" y="468.247">CLK</tspan>
|
||||
</text>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="353.502" y="472.997">
|
||||
<tspan x="353.502" y="472.997">DI</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.49" y1="456.922" x2="322.143" y2="456.922"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.378" y1="461.909" x2="322.268" y2="461.922"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.753" y1="467.009" x2="322.143" y2="467.047"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.893" y1="471.672" x2="322.018" y2="471.672"/>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="458.372">
|
||||
<tspan x="323.752" y="458.372">CS</tspan>
|
||||
</text>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.127" y="468.497">
|
||||
<tspan x="324.127" y="468.497">WP</tspan>
|
||||
</text>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="472.997">
|
||||
<tspan x="323.752" y="472.997">GND</tspan>
|
||||
</text>
|
||||
<text font-size="4.51549" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.127" y="463.497">
|
||||
<tspan x="324.127" y="463.497">DO</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.852" y1="454.397" x2="323.902" y2="454.409"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.802" y1="464.397" x2="323.852" y2="464.409"/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="368.252" y1="456.797" x2="373.902" y2="456.784"/>
|
||||
<g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="374.027" y1="456.784" x2="374.027" y2="438.895"/>
|
||||
<polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="375.027,439.777 374.027,437.777 373.027,439.777 "/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="314.277" y1="471.784" x2="314.277" y2="479.659"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="317.027" y1="479.659" x2="311.502" y2="479.672"/>
|
||||
<g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" x1="374.027" y1="443.284" x2="374.027" y2="447.434"/>
|
||||
<polygon style="fill: #000000" points="372.027,447.434 374.027,451.434 376.027,447.434 "/>
|
||||
<polygon style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" points="372.027,447.434 374.027,451.434 376.027,447.434 "/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1.2; stroke: #000000" x1="370.402" y1="452.032" x2="377.527" y2="452.032"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 5.0 KiB |
@@ -1,55 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
|
||||
<svg width="4cm" height="3cm" viewBox="311 435 65 45" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<g>
|
||||
<g>
|
||||
<rect style="fill: #ffffff" x="322.124" y="451.034" width="37.75" height="26.6444"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="322.124" y="451.034" width="37.75" height="26.6444"/>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="340.999" y="465.734">
|
||||
<tspan x="340.999" y="465.734"></tspan>
|
||||
</text>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.874" y1="456.784" x2="368.528" y2="456.784"/>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="348.75" y="457.91">
|
||||
<tspan x="348.75" y="457.91">VCC</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="359.762" y1="461.772" x2="368.652" y2="461.784"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.138" y1="466.872" x2="368.528" y2="466.91"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="360.278" y1="471.534" x2="368.402" y2="471.534"/>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="345.752" y="463.246">
|
||||
<tspan x="345.752" y="463.246">HOLD</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="346.652" y1="459.16" x2="358.402" y2="459.16"/>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="349.752" y="468.246">
|
||||
<tspan x="349.752" y="468.246">CLK</tspan>
|
||||
</text>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="353.502" y="472.996">
|
||||
<tspan x="353.502" y="472.996">DI</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.49" y1="456.922" x2="322.142" y2="456.922"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.378" y1="461.91" x2="322.268" y2="461.922"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.752" y1="467.01" x2="322.142" y2="467.046"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="313.892" y1="471.672" x2="322.018" y2="471.672"/>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="458.372">
|
||||
<tspan x="323.752" y="458.372">CS</tspan>
|
||||
</text>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.128" y="468.496">
|
||||
<tspan x="324.128" y="468.496">WP</tspan>
|
||||
</text>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="323.752" y="472.996">
|
||||
<tspan x="323.752" y="472.996">GND</tspan>
|
||||
</text>
|
||||
<text font-size="4.51556" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="324.128" y="463.496">
|
||||
<tspan x="324.128" y="463.496">DO</tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.852" y1="454.396" x2="323.902" y2="454.41"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 0.2; stroke: #000000" x1="330.802" y1="464.396" x2="323.852" y2="464.41"/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="368.252" y1="456.796" x2="373.902" y2="456.784"/>
|
||||
<g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="374.028" y1="456.784" x2="374.028" y2="438.896"/>
|
||||
<polyline style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" points="375.028,439.778 374.028,437.778 373.028,439.778 "/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="314.278" y1="471.784" x2="314.278" y2="479.66"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x1="317.028" y1="479.66" x2="311.502" y2="479.672"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 4.5 KiB |
@@ -1,111 +0,0 @@
|
||||
# Flashing firmware tutorial
|
||||
|
||||
Updating the firmware is possible using the **internal method**, where the updates
|
||||
happen from a running system, or using the **external method**, where the system
|
||||
is in a shut down state and an external programmer is attached to write into the
|
||||
flash IC.
|
||||
|
||||
## Contents
|
||||
|
||||
* [Flashing internaly](int_flashrom.md)
|
||||
* [Flashing firmware standalone](ext_standalone.md)
|
||||
* [Flashing firmware externally supplying direct power](ext_power.md)
|
||||
* [Flashing firmware externally without supplying direct power](no_ext_power.md)
|
||||
|
||||
## General advice
|
||||
|
||||
* It's recommended to only flash the BIOS region.
|
||||
* Always verify the firmware image.
|
||||
* If you flash externally and have transmission errors:
|
||||
* Use short wires
|
||||
* Reduce clock frequency
|
||||
* Check power supply
|
||||
* Make sure that there are no other bus masters (EC, ME, SoC, ...)
|
||||
|
||||
## Internal method
|
||||
|
||||
This method using [flashrom] is available on many platforms, as long as they
|
||||
aren't locked down.
|
||||
|
||||
There are various protection schemes that make it impossible to modify or
|
||||
replace a firmware from a running system. coreboot allows to disable these
|
||||
mechanisms, making it possible to overwrite (or update) the firmware from a
|
||||
running system.
|
||||
|
||||
Usually you must use the **external method** once to install a retrofitted
|
||||
coreboot and then you can use the **internal method** for future updates.
|
||||
|
||||
There are multiple ways to update the firmware:
|
||||
* Using flashrom's *internal* programmer to directly write into the firmware
|
||||
flash IC, running on the target machine itself
|
||||
* A proprietary software to update the firmware, running on the target machine
|
||||
itself
|
||||
* A UEFI firmware update capsule
|
||||
|
||||
More details on flashrom's
|
||||
* [internal programmer](int_flashrom.md)
|
||||
|
||||
## External method
|
||||
|
||||
External flashing is possible on many platforms, but requires disassembling
|
||||
the target hardware. You need to buy a flash programmer, that
|
||||
exposes the same interface as your flash IC (likely SPI).
|
||||
|
||||
Please also have a look at the mainboard-specific documentation for details.
|
||||
|
||||
After exposing the firmware flash IC, read the schematics and use one of the
|
||||
possible methods:
|
||||
|
||||
* [Flashing firmware standalone](ext_standalone.md)
|
||||
* [Flashing firmware externally supplying direct power](ext_power.md)
|
||||
* [Flashing firmware externally without supplying direct power](no_ext_power.md)
|
||||
|
||||
**WARNING:** Using the wrong method or accidentally using the wrong pinout might
|
||||
permanently damage your hardware!
|
||||
|
||||
**WARNING:** Do not rely on dots *painted* on flash ICs to orient the pins!
|
||||
Any dots painted on flash ICs may only indicate if they've been tested. Dots
|
||||
that appear in datasheets to indicate pin 1 correspond to some kind of physical
|
||||
marker, such as a drilled hole, or one side being more flat than the other.
|
||||
|
||||
## Using a layout file
|
||||
On platforms where the flash IC is shared with other components you might want
|
||||
to write only a part of the flash IC. On Intel for example there are IFD, ME and
|
||||
GBE which don't need to be updated to install coreboot.
|
||||
To make [flashrom] only write the *bios* region, leaving Intel ME and Intel IFD
|
||||
untouched, you can use a layout file, which can be created with ifdtool and a backup
|
||||
of the original firmware.
|
||||
|
||||
```bash
|
||||
ifdtool -f rom.layout backup.rom
|
||||
```
|
||||
|
||||
and looks similar to:
|
||||
|
||||
```
|
||||
00000000:00000fff fd
|
||||
00500000:00bfffff bios
|
||||
00003000:004fffff me
|
||||
00001000:00002fff gbe
|
||||
```
|
||||
|
||||
By specifying *-l* and *-i* [flashrom] writes a single region:
|
||||
```bash
|
||||
flashrom -l rom.layout -i bios -w coreboot.rom -p <programmer>
|
||||
```
|
||||
|
||||
## Using an IFD to determine the layout
|
||||
flashrom version 1.0 supports reading the layout from the IFD (first 4KiB of
|
||||
the ROM). You don't need to manually specify a layout it, but it only works
|
||||
under the following conditions:
|
||||
|
||||
* Only available on Intel ICH7+
|
||||
* There's only one flash IC when flashing externally
|
||||
|
||||
```bash
|
||||
flashrom --ifd -i bios -w coreboot.rom -p <programmer>
|
||||
```
|
||||
|
||||
**TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms
|
||||
|
||||
[flashrom]: https://www.flashrom.org/Flashrom
|
||||
@@ -1,19 +0,0 @@
|
||||
# Flashing firmware internally
|
||||
|
||||
**WARNING:** If you flash a broken firmware and have no recovery mechanism, you
|
||||
must use the **external method** to flash a working firmware again.
|
||||
|
||||
## Using flashrom
|
||||
This method does only work on Linux, if it isn't locked down.
|
||||
You may also need to boot with `iomem=relaxed` in the kernel command
|
||||
line if CONFIG_IO_STRICT_DEVMEM is set.
|
||||
|
||||
|
||||
For more details please also check [flashrom's wiki].
|
||||
Use the programmer *internal* to flash *coreboot.rom* internally:
|
||||
|
||||
```bash
|
||||
flashrom -p internal -w coreboot.rom
|
||||
```
|
||||
|
||||
[flashrom's wiki]: https://www.flashrom.org/Flashrom
|
||||
@@ -1,22 +0,0 @@
|
||||
# Flashing firmware externally supplying no power
|
||||
|
||||
On some mainboards the flash IC's Vcc pin is connected to the internal
|
||||
power-rail, powering the entire board if the flash IC is powered externally.
|
||||
Likely it powers other chips which access the flash IC, preventing the external
|
||||
programmer from reading/writing the chip. It also violates the components'
|
||||
power sequence, bringing the ICs into an undefined state.
|
||||
|
||||
![][flash_ic_no_diode]
|
||||
|
||||
Please have a look at the mainboard specific documentation for details.
|
||||
|
||||
On those boards it's recommended to use a programmer without supplying power
|
||||
externally.
|
||||
|
||||
The key to read and write the flash IC is to put the machine into *S3* sleep-
|
||||
state or *S5* sleep-state *maybe* with Wake-On-LAN enabled.
|
||||
Another option that sometimes works is to keep the device in reset. This method requires
|
||||
knowledge of the board schematics and might require hardware modifications.
|
||||
Use a multimeter to make sure the flash IC is powered in those sleep states.
|
||||
|
||||
[flash_ic_no_diode]: flash_ic_no_diode.svg
|
||||
@@ -13,8 +13,8 @@ here, please discuss it in the mailing list to get this document updated.
|
||||
Don't just assume that it's okay, even if someone on IRC says it is.
|
||||
|
||||
|
||||
Summary
|
||||
-------
|
||||
Summary:
|
||||
--------
|
||||
These are the expectations for committing, reviewing, and submitting code
|
||||
into coreboot git and gerrit. While breaking individual rules may not have
|
||||
immediate consequences, the coreboot leadership may act on repeated or
|
||||
@@ -33,8 +33,8 @@ addresses.
|
||||
* Don’t submit patches that you know will break other platforms.
|
||||
|
||||
|
||||
More detail
|
||||
-----------
|
||||
More detail:
|
||||
------------
|
||||
* Don't violate the licenses. If you're submitting code that you didn't
|
||||
write yourself, make sure the license is compatible with the license of the
|
||||
project you're submitting the changes to. If you’re submitting code that
|
||||
@@ -43,42 +43,15 @@ 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](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
|
||||
let coreboot developers around the world have a chance to review. Complex
|
||||
reworks, even if they don't change the purpose of the patch but the way
|
||||
it's implemented, should restart the wait period.
|
||||
|
||||
* A change can go in without the wait period if its purpose is to fix
|
||||
a recently-introduced issue (build, boot or OS-level compatibility, not
|
||||
necessarily identified by coreboot.org facilities). Its commit message
|
||||
has to explain what change introduced the problem and the nature of
|
||||
the problem so that the emergency need becomes apparent. The change
|
||||
itself should be as limited in scope and impact as possible to make it
|
||||
simple to assess the impact. Such a change can be merged early with 3
|
||||
Code-Review+2. For emergency fixes that affect a single project (SoC,
|
||||
mainboard, ...) it's _strongly_ recommended to get a review by somebody
|
||||
not involved with that project to ensure that the documentation of the
|
||||
issue is clear enough.
|
||||
|
||||
* Trivial changes that deal with minor issues like inconsistencies in
|
||||
whitespace or spelling fixes that don't impact the final binary output
|
||||
also don't need to wait. Such changes should point out in their commit
|
||||
messages how the the author verified that the binary output is identical
|
||||
(e.g. a TIMELESS build for a given configuration). When submitting
|
||||
such changes early, the submitter must be different from the author
|
||||
and must document the intent in the Gerrit discussion, e.g. "landed the
|
||||
change early because it's trivial". Note that trivial fixes shouldn't
|
||||
necessarily be expedited: Just like they're not critical enough for
|
||||
things to go wrong because of them, they're not critical enough to
|
||||
require quick handling. This exception merely serves to acknowledge that
|
||||
a round-the-world review just isn't necessary for some types of changes.
|
||||
|
||||
* As explained in our Code of Conduct, we try to assume the best of each
|
||||
other in this community. It's okay to discuss mistakes (e.g. isolated
|
||||
instances of non-trivial and non-critical changes submitted early) but
|
||||
try to keep such inquiries blameless. If a change leads to problems with
|
||||
our code, the focus should be on fixing the issue, not on assigning blame.
|
||||
* Let non-trivial patches sit in a review state for at least 24 hours
|
||||
before submission. Remember that there are coreboot developers in timezones
|
||||
all over the world, and everyone should have a chance to contribute.
|
||||
Trivial patches would be things like whitespace changes or spelling fixes.
|
||||
In general, small changes that don’t impact the final binary output. The
|
||||
24-hour period would start at submission, and would be restarted at any
|
||||
update which significantly changes any part of the patch. Patches can be
|
||||
'Fast-tracked' and submitted in under this 24 hour with the agreement of at
|
||||
least 3 +2 votes.
|
||||
|
||||
* Do not +2 patches that you authored or own, even for something as trivial
|
||||
as whitespace fixes. When working on your own patches, it’s easy to
|
||||
@@ -125,8 +98,8 @@ must at least provide a path that will allow other platforms to continue
|
||||
working.
|
||||
|
||||
|
||||
Recommendations for gerrit activity
|
||||
-----------------------------------
|
||||
Recommendations for gerrit activity:
|
||||
------------------------------------
|
||||
These guidelines are less strict than the ones listed above. These are more
|
||||
of the “good idea” variety. You are requested to follow the below
|
||||
guidelines, but there will probably be no actual consequences if they’re
|
||||
@@ -177,8 +150,8 @@ together so people can easily see the connection at the top level of
|
||||
gerrit. Topics can be set for individual patches in gerrit by going into
|
||||
the patch and clicking on the icon next to the topic line. Topics can also
|
||||
be set when you push the patches into gerrit. For example, to push a set of
|
||||
commits with the i915-kernel-x60 set, use the command:
|
||||
git push origin HEAD:refs/for/master%topic=i915-kernel-x60
|
||||
commits with the the i915-kernel-x60 set, use the command:
|
||||
git push origin HEAD:refs/for/master/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
|
||||
@@ -186,19 +159,15 @@ this is by marking in the commit message that it’s not ready until X. The
|
||||
commit message can be updated easily when it’s ready to be pushed.
|
||||
Examples of this are "WIP: title" or "[NEEDS_TEST]: title". Another way to
|
||||
mark the patch as not ready would be to give it a -1 or -2 review, but
|
||||
isn't as obvious as the commit message. These patches can also be pushed with
|
||||
the wip flag:
|
||||
git push origin HEAD:refs/for/master%wip
|
||||
isn't as obvious as the commit message. These patches can also be pushed as
|
||||
drafts as shown in the next guideline.
|
||||
|
||||
* When pushing patches that are not for submission, these should be marked
|
||||
as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as
|
||||
private changes, so that only explicitly added reviewers will see them. These
|
||||
draft commits, so that only explicitly added reviewers will see them. These
|
||||
sorts of patches are frequently posted as ideas or RFCs for the community
|
||||
to look at. To push a private change, use the command:
|
||||
git push origin HEAD:refs/for/master%private
|
||||
|
||||
* Multiple push options can be combined:
|
||||
git push origin HEAD:refs/for/master%private,wip,topic=experiment
|
||||
to look at. To push a draft, use the command:
|
||||
git push origin HEAD:refs/drafts/master
|
||||
|
||||
* 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
|
||||
@@ -281,26 +250,9 @@ commit message itself:
|
||||
The script 'util/gitconfig/rebase.sh' can be used to help automate this.
|
||||
Other tags such as 'Commit-Queue' can simply be removed.
|
||||
|
||||
* Check if there's documentation that needs to be updated to remain current
|
||||
after your change. If there's no documentation for the part of coreboot
|
||||
you're working on, consider adding some.
|
||||
|
||||
* When contributing a significant change to core parts of the code base (such
|
||||
as the boot state machine or the resource allocator), or when introducing
|
||||
a new way of doing something that you think is worthwhile to apply across
|
||||
the tree (e.g. board variants), please bring up your design on the [mailing
|
||||
list](../community/forums.md). When changing behavior substantially, an
|
||||
explanation of what changes and why may be useful to have, either in the
|
||||
commit message or, if the discussion of the subject matter needs way more
|
||||
space, in the documentation. Since "what we did in the past and why it isn't
|
||||
appropriate anymore" isn't the most useful reading several years down the road,
|
||||
such a description could be put into the release notes for the next version
|
||||
(that you can find in Documentation/releases/) where it will inform people
|
||||
now without cluttering up the regular documentation, and also gives a nice
|
||||
shout-out to your contribution by the next release.
|
||||
|
||||
Expectations contributors should have
|
||||
-------------------------------------
|
||||
Expectations contributors should have:
|
||||
--------------------------------------
|
||||
* Don't expect that people will review your patch unless you ask them to.
|
||||
Adding other people as reviewers is the easiest way. Asking for reviews for
|
||||
individual patches in the IRC channel, or by sending a direct request to an
|
||||
@@ -1,105 +0,0 @@
|
||||
# coreboot architecture
|
||||
|
||||
## Overview
|
||||
![][architecture]
|
||||
|
||||
[architecture]: comparision_coreboot_uefi.svg
|
||||
|
||||
## Stages
|
||||
coreboot consists of multiple stages that are compiled as separate binaries and
|
||||
are inserted into the CBFS with custom compression. The bootblock usually doesn't
|
||||
have compression while the ramstage and payload are compressed with LZMA.
|
||||
|
||||
Each stage loads the next stage at given address (possibly decompressing it).
|
||||
|
||||
Some stages are relocatable and can be placed anywhere in DRAM. Those stages are
|
||||
usually cached in CBMEM for faster loading times on ACPI S3 resume.
|
||||
|
||||
Supported stage compressions:
|
||||
* none
|
||||
* LZ4
|
||||
* LZMA
|
||||
|
||||
## bootblock
|
||||
The bootblock is the first stage executed after CPU reset. It is written in
|
||||
assembly language and its main task is to set up everything for a C-environment:
|
||||
|
||||
Common tasks:
|
||||
|
||||
* Cache-As-RAM for heap and stack
|
||||
* Set stack pointer
|
||||
* Clear memory for BSS
|
||||
* Decompress and load the next stage
|
||||
|
||||
On x86 platforms that includes:
|
||||
|
||||
* Microcode updates
|
||||
* Timer init
|
||||
* Switching from 16-bit real-mode to 32-bit protected mode
|
||||
|
||||
The bootblock loads the romstage or the verstage if verified boot is enabled.
|
||||
|
||||
### Cache-As-Ram
|
||||
The *Cache-As-Ram*, also called Non-Eviction mode, or *CAR* allows to use the
|
||||
CPU cache like regular SRAM. This is particullary usefull for high level
|
||||
languages like `C`, which need RAM for heap and stack.
|
||||
|
||||
The CAR needs to be activated using vendor specific CPU instructions.
|
||||
|
||||
The following stages run when Cache-As-Ram is active:
|
||||
* bootblock
|
||||
* romstage
|
||||
* verstage
|
||||
* postcar
|
||||
|
||||
## verstage
|
||||
The verstage is where the root-of-trust starts. It's assumed that
|
||||
it cannot be overwritten in-field (together with the public key) and
|
||||
it starts at the very beginning of the boot process.
|
||||
The verstage installs a hook to verify a file before it's loaded from
|
||||
CBFS or a partition before it's accessed.
|
||||
|
||||
The verified boot mechanism allows trusted in-field firmware updates
|
||||
combined with a fail-safe recovery mode.
|
||||
|
||||
## romstage
|
||||
The romstage initializes the DRAM and prepares everything for device init.
|
||||
|
||||
Common tasks:
|
||||
|
||||
* Early device init
|
||||
* DRAM init
|
||||
|
||||
## postcar
|
||||
To leave the CAR setup and run code from regular DRAM the postcar-stage tears
|
||||
down CAR and loads the ramstage. Compared to other stages it's minimal in size.
|
||||
|
||||
## ramstage
|
||||
|
||||
The ramstage does the main device init:
|
||||
|
||||
* PCI device init
|
||||
* On-chip device init
|
||||
* TPM init (if not done by verstage)
|
||||
* Graphics init (optional)
|
||||
* CPU init (like set up SMM)
|
||||
|
||||
After initialization tables are written to inform the payload or operating system
|
||||
about the current hardware existance and state. That includes:
|
||||
|
||||
* ACPI tables (x86 specific)
|
||||
* SMBIOS tables (x86 specific)
|
||||
* coreboot tables
|
||||
* devicetree updates (ARM specific)
|
||||
|
||||
It also does hardware and firmware lockdown:
|
||||
* Write-protection of boot media
|
||||
* Lock security related registers
|
||||
* Lock SMM mode (x86 specific)
|
||||
|
||||
## payload
|
||||
The payload is the software that is run after coreboot is done. It resides in
|
||||
the CBFS and there's no possibility to choose it at runtime.
|
||||
|
||||
For more details have a look at [payloads](../payloads.md).
|
||||
|
||||
Binary file not shown.
@@ -1,176 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
|
||||
<svg width="55cm" height="28cm" viewBox="62 37 1088 559" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<g>
|
||||
<rect style="fill: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="242.613" y1="107.463" x2="242.698" y2="492.591"/>
|
||||
<g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="234.964" y1="477.053" x2="1135.15" y2="478.109"/>
|
||||
<polyline style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" points="1124.61,485.597 1139.62,478.114 1124.63,470.597 "/>
|
||||
</g>
|
||||
<text font-size="22.5778" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="482.342" y="58.1574">
|
||||
<tspan x="482.342" y="58.1574">Platform Initialization Firmware Phases</tspan>
|
||||
</text>
|
||||
<text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="98.4514" y="435.714">
|
||||
<tspan x="98.4514" y="435.714">EDK II - stages</tspan>
|
||||
</text>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="1073.49" y="499.998">
|
||||
<tspan x="1073.49" y="499.998">time</tspan>
|
||||
</text>
|
||||
<text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="82.8266" y="330.476">
|
||||
<tspan x="82.8266" y="330.476">coreboot - stages</tspan>
|
||||
</text>
|
||||
<g>
|
||||
<rect style="fill: #faff94" x="250.501" y="404.247" width="130.432" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="250.501" y="404.247" width="130.432" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="315.718" y="434.72">
|
||||
<tspan x="315.718" y="434.72">Security</tspan>
|
||||
<tspan x="315.718" y="450.72">(SEC)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #faff94" x="383.033" y="404.781" width="282.702" height="69"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="383.033" y="404.781" width="282.702" height="69"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="524.384" y="427.181">
|
||||
<tspan x="524.384" y="427.181">Pre-EFI</tspan>
|
||||
<tspan x="524.384" y="443.181">Initialization Environment</tspan>
|
||||
<tspan x="524.384" y="459.181">(PEI)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #faff94" x="668.027" y="405.317" width="269.244" height="69"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="668.027" y="405.317" width="269.244" height="69"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="802.649" y="427.717">
|
||||
<tspan x="802.649" y="427.717">Driver Execution</tspan>
|
||||
<tspan x="802.649" y="443.717">Environment</tspan>
|
||||
<tspan x="802.649" y="459.717">(DXE)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #faff94" x="939.541" y="405.727" width="178.75" height="69"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="939.541" y="405.727" width="178.75" height="69"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1028.92" y="436.127">
|
||||
<tspan x="1028.92" y="436.127">Boot Device Selection</tspan>
|
||||
<tspan x="1028.92" y="452.127">(BDS)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="254.747" y="291.309" width="125.314" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="254.747" y="291.309" width="125.314" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="317.404" y="329.782">
|
||||
<tspan x="317.404" y="329.782">bootblock</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="476.354" y="290.735" width="89.65" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="476.354" y="290.735" width="89.65" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="521.179" y="329.209">
|
||||
<tspan x="521.179" y="329.209">romstage</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="382.317" y="291.011" width="92.1" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="382.317" y="291.011" width="92.1" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="428.367" y="321.485">
|
||||
<tspan x="428.367" y="321.485">verstage</tspan>
|
||||
<tspan x="428.367" y="337.485">(optional)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="617.11" y="321.464">
|
||||
<tspan x="617.11" y="321.464">postcar</tspan>
|
||||
<tspan x="617.11" y="337.464">(x86 only)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="667.529" y="281.527" width="168.747" height="37"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.529" y="281.527" width="168.747" height="37"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.903" y="303.927">
|
||||
<tspan x="751.903" y="303.927">ramstage</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="667.84" y="321.487" width="167.519" height="53"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.84" y="321.487" width="167.519" height="53"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.6" y="343.887">
|
||||
<tspan x="751.6" y="343.887">SMM</tspan>
|
||||
<tspan x="751.6" y="359.887">(x86 only)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="941.841" y="283.151" width="171.98" height="69.1471"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="941.841" y="283.151" width="171.98" height="69.1471"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1027.83" y="321.624">
|
||||
<tspan x="1027.83" y="321.624">payload</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #d8e5e5" x="253.112" y="209.178" width="82.7" height="27"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="253.112" y="209.178" width="82.7" height="27"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="294.462" y="226.578">
|
||||
<tspan x="294.462" y="226.578">Assembly</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #00c800" x="318.155" y="129.267" width="283.43" height="27"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="318.155" y="129.267" width="283.43" height="27"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="459.87" y="146.667">
|
||||
<tspan x="459.87" y="146.667">Cache-As-RAM</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #ff8484" x="506.676" y="159.67" width="599.421" height="27"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="506.676" y="159.67" width="599.421" height="27"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="806.387" y="177.07">
|
||||
<tspan x="806.387" y="177.07">DRAM</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.046" y1="392.926" x2="1113.82" y2="391.893"/>
|
||||
<text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="387.045" y="241.637">
|
||||
<tspan x="387.045" y="241.637"></tspan>
|
||||
</text>
|
||||
<g>
|
||||
<rect style="fill: #ffffff" x="337.438" y="209.383" width="618.831" height="27"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="337.438" y="209.383" width="618.831" height="27"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="646.853" y="226.783">
|
||||
<tspan x="646.853" y="226.783">C</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect style="fill: #f6c7c7" x="667.35" y="238.912" width="170.3" height="27"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.35" y="238.912" width="170.3" height="27"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="752.5" y="256.312">
|
||||
<tspan x="752.5" y="256.312">ADA SPARK (x86 only)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="84.2481" y="233.28">
|
||||
<tspan x="84.2481" y="233.28">coreboot</tspan>
|
||||
<tspan x="84.2481" y="254.446">source languages</tspan>
|
||||
</text>
|
||||
<text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="86.5008" y="153.786">
|
||||
<tspan x="86.5008" y="153.786">code/heap</tspan>
|
||||
<tspan x="86.5008" y="174.953">memory location </tspan>
|
||||
</text>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.483" y1="273.35" x2="1109.07" y2="273.582"/>
|
||||
<line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="176.24" y1="192.463" x2="1109.66" y2="192.132"/>
|
||||
<g>
|
||||
<rect style="fill: #90c9ff" x="838.583" y="281.963" width="100.3" height="53"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="838.583" y="281.963" width="100.3" height="53"/>
|
||||
<text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="888.733" y="304.363">
|
||||
<tspan x="888.733" y="304.363">BL31</tspan>
|
||||
<tspan x="888.733" y="320.363">(ARM only)</tspan>
|
||||
</text>
|
||||
</g>
|
||||
<text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="209.772" y="508.772">
|
||||
<tspan x="209.772" y="508.772">Power on</tspan>
|
||||
</text>
|
||||
<g>
|
||||
<rect style="fill: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
|
||||
<rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
|
||||
</g>
|
||||
<path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 955.029 209.941 C 967.678,210.1 946.349,230.772 955.598,237.021"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 12 KiB |
@@ -1,131 +0,0 @@
|
||||
# Configuring a mainboard's GPIOs in coreboot
|
||||
|
||||
## Introduction
|
||||
|
||||
Every mainboard needs to appropriately configure its General Purpose Inputs /
|
||||
Outputs (GPIOs). There are many facets of this issue, including which boot
|
||||
stage a GPIO might need to be configured.
|
||||
|
||||
## Boot stages
|
||||
|
||||
Typically, coreboot does most of its non-memory related initialization work in
|
||||
ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
|
||||
are configured in this stage. However, some boards might need a few GPIOs
|
||||
configured before that; think of memory strapping pins which indicate what kind
|
||||
of DRAM is installed. These pins might need to be read before initializing the
|
||||
memory, so these GPIOs are then typically configured in bootblock or romstage.
|
||||
|
||||
## Configuration
|
||||
|
||||
Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
|
||||
file typically contains tables which describe the configuration of the GPIO
|
||||
registers. Since these registers could be different on a per-SoC or per
|
||||
SoC-family basis, you may need to consult the datasheet for your SoC to find out
|
||||
how to appropriately set these registers. In addition, some mainboards are
|
||||
based on a baseboard/variant model, where several variant mainboards may share a
|
||||
lot of their circuitry and ICs and the commonality between the boards is
|
||||
collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
|
||||
between multiple boards are placed in the baseboard's ``gpio.c`` file, while the
|
||||
ones that are board-specific go into each variant's ``gpio.c`` file.
|
||||
|
||||
## Intel SoCs
|
||||
|
||||
Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
|
||||
has been taken advantage of in coreboot, which has a large set of macros that
|
||||
can be used to describe the configuration of each GPIO pad. This file lives in
|
||||
``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
|
||||
|
||||
### Older Intel SoCs
|
||||
|
||||
Baytrail and Braswell, for example, simply expect the mainboard to supply a
|
||||
callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
|
||||
objects, defining the configuration of each pin.
|
||||
|
||||
### AMD SoCs
|
||||
|
||||
Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
|
||||
register values configuring each pin, similar to Intel.
|
||||
|
||||
### Register details
|
||||
|
||||
GPIO configuration registers typically control properties such as:
|
||||
1. Input / Output
|
||||
2. Pullups / Pulldowns
|
||||
3. Termination
|
||||
4. Tx / Rx Disable
|
||||
5. Which reset signal to use
|
||||
6. Native Function / IO
|
||||
7. Interrupts
|
||||
* IRQ routing (e.g. on x86, APIC, SCI, SMI)
|
||||
* Edge or Level Triggered
|
||||
* Active High or Active Low
|
||||
8. Debouncing
|
||||
|
||||
## Configuring GPIOs for pre-ramstage
|
||||
|
||||
coreboot provides for several SoC-specific and mainboard-specific callbacks at
|
||||
specific points in time, such as bootblock-early, bootblock, romstage entry,
|
||||
pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
|
||||
configured in either bootblock or romstage, depending on when they are needed,
|
||||
are denoted the "early" GPIOs. Some mainboard will use
|
||||
``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
|
||||
probably a good place to start. Many mainboards will declare their GPIO
|
||||
configuration as structs, i.e. (Intel),
|
||||
|
||||
```C
|
||||
struct pad_config {
|
||||
/* offset of pad within community */
|
||||
int pad;
|
||||
/* Pad config data corresponding to DW0, DW1,.... */
|
||||
uint32_t pad_config[GPIO_NUM_PAD_CFG_REGS];
|
||||
};
|
||||
```
|
||||
|
||||
and will usually place these in an array, one for each pad to be configured.
|
||||
Mainboards using Intel SoCs can use a library which combines common
|
||||
configurations together into a set of macros, e.g.,
|
||||
|
||||
```C
|
||||
/* Native function configuration */
|
||||
#define PAD_CFG_NF(pad, pull, rst, func)
|
||||
/* General purpose output, no pullup/down. */
|
||||
#define PAD_CFG_GPO(pad, val, rst)
|
||||
/* General purpose output, with termination specified */
|
||||
#define PAD_CFG_TERM_GPO(pad, val, pull, rst)
|
||||
/* General purpose output, no pullup/down. */
|
||||
#define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
|
||||
/* General purpose input */
|
||||
#define PAD_CFG_GPI(pad, pull, rst)
|
||||
```
|
||||
etc.
|
||||
|
||||
## Configuring GPIOs for ramstage and beyond...
|
||||
|
||||
In ramstage, most mainboards will configure the rest of their GPIOs for the
|
||||
function they will be performing while the device is active. The goal is the
|
||||
same as above in bootblock; another ``static const`` array is created, and the
|
||||
rest of the GPIO registers are programmed.
|
||||
|
||||
In the baseboard/variant model described above, the baseboard will provide the
|
||||
configuration for the GPIOs which are configured identically between variants,
|
||||
and will provide a mechanism for a variant to override the baseboard's
|
||||
configuration. This is usually done via two tables: the baseboard table and the
|
||||
variant's override table.
|
||||
|
||||
This configuration is often hooked into the mainboard's `enable_dev` callback,
|
||||
defined in its `struct chip_operations`.
|
||||
|
||||
## Potential issues (gotchas!)
|
||||
|
||||
There are a couple of configurations that you need to especially careful about,
|
||||
as they can have a large impact on your mainboard.
|
||||
|
||||
The first is configuring a pin as an output, when it was designed to be an
|
||||
input. There is a real risk in this case of short-circuiting a component which
|
||||
could cause catastrophic failures, up to and including your mainboard!
|
||||
|
||||
The other configuration option to watch out for deals with unconnected GPIOs.
|
||||
If no pullup or pulldown is declared with these, they may end up "floating",
|
||||
i.e., not at logical high or logical low. This can cause problems such as
|
||||
unwanted power consumption or not reading the pin correctly, if it was intended
|
||||
to be strapped.
|
||||
@@ -1,10 +0,0 @@
|
||||
# Getting Started
|
||||
|
||||
* [coreboot architecture](architecture.md)
|
||||
* [Build System](build_system.md)
|
||||
* [Submodules](submodules.md)
|
||||
* [Kconfig](kconfig.md)
|
||||
* [Gerrit Guidelines](gerrit_guidelines.md)
|
||||
* [Documentation License](license.md)
|
||||
* [Writing Documentation](writing_documentation.md)
|
||||
* [Setting up GPIOs](gpio.md)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,164 +0,0 @@
|
||||
# coreboot documentation license
|
||||
|
||||
Files under Documentation/ are licensed under CC-BY 4.0 terms, printed below.
|
||||
As an exception, files under Documentation/ with a history older than 2017-05-24
|
||||
might be under different licenses (but should be cleared up ASAP).
|
||||
|
||||
## Attribution 4.0 International
|
||||
|
||||
Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
|
||||
|
||||
### Using Creative Commons Public Licenses
|
||||
|
||||
Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
|
||||
|
||||
* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
|
||||
|
||||
* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
|
||||
|
||||
## Creative Commons Attribution 4.0 International Public License
|
||||
|
||||
By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
|
||||
|
||||
### Section 1 – Definitions.
|
||||
|
||||
a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
|
||||
|
||||
b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
|
||||
|
||||
c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
|
||||
|
||||
d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
|
||||
|
||||
e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
|
||||
|
||||
f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
|
||||
|
||||
g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
|
||||
|
||||
h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
|
||||
|
||||
i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
|
||||
|
||||
j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
|
||||
|
||||
k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
|
||||
|
||||
### Section 2 – Scope.
|
||||
|
||||
a. ___License grant.___
|
||||
|
||||
1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
|
||||
|
||||
A. reproduce and Share the Licensed Material, in whole or in part; and
|
||||
|
||||
B. produce, reproduce, and Share Adapted Material.
|
||||
|
||||
2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
|
||||
|
||||
3. __Term.__ The term of this Public License is specified in Section 6(a).
|
||||
|
||||
4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
|
||||
|
||||
5. __Downstream recipients.__
|
||||
|
||||
A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
|
||||
|
||||
B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
|
||||
|
||||
6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
|
||||
|
||||
b. ___Other rights.___
|
||||
|
||||
1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
|
||||
|
||||
2. Patent and trademark rights are not licensed under this Public License.
|
||||
|
||||
3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
|
||||
|
||||
### Section 3 – License Conditions.
|
||||
|
||||
Your exercise of the Licensed Rights is expressly made subject to the following conditions.
|
||||
|
||||
a. ___Attribution.___
|
||||
|
||||
1. If You Share the Licensed Material (including in modified form), You must:
|
||||
|
||||
A. retain the following if it is supplied by the Licensor with the Licensed Material:
|
||||
|
||||
i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
|
||||
|
||||
ii. a copyright notice;
|
||||
|
||||
iii. a notice that refers to this Public License;
|
||||
|
||||
iv. a notice that refers to the disclaimer of warranties;
|
||||
|
||||
v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
|
||||
|
||||
B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
|
||||
|
||||
C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
|
||||
|
||||
2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
|
||||
|
||||
3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
|
||||
|
||||
4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
|
||||
|
||||
### Section 4 – Sui Generis Database Rights.
|
||||
|
||||
Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
|
||||
|
||||
a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
|
||||
|
||||
b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
|
||||
|
||||
c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
|
||||
|
||||
For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
|
||||
|
||||
### Section 5 – Disclaimer of Warranties and Limitation of Liability.
|
||||
|
||||
a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
|
||||
|
||||
b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
|
||||
|
||||
c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
|
||||
|
||||
### Section 6 – Term and Termination.
|
||||
|
||||
a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
|
||||
|
||||
b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
|
||||
|
||||
1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
|
||||
|
||||
2. upon express reinstatement by the Licensor.
|
||||
|
||||
For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
|
||||
|
||||
c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
|
||||
|
||||
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
|
||||
|
||||
### Section 7 – Other Terms and Conditions.
|
||||
|
||||
a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
|
||||
|
||||
b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
|
||||
|
||||
### Section 8 – Interpretation.
|
||||
|
||||
a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
|
||||
|
||||
b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
|
||||
|
||||
c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
|
||||
|
||||
d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
|
||||
|
||||
> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
|
||||
>
|
||||
> Creative Commons may be contacted at creativecommons.org
|
||||
|
||||
@@ -1,163 +0,0 @@
|
||||
# coreboot documentation guidelines
|
||||
|
||||
> Documentation is like sex: when it is good, it is very, very good;
|
||||
> and when it is bad, it is better than nothing.
|
||||
|
||||
That said please always try to write documentation! One problem in the
|
||||
firmware development is the missing documentation. In this document
|
||||
you will get a brief introduction how to write, submit and publish
|
||||
documenation to coreboot.
|
||||
|
||||
## Preparations
|
||||
|
||||
coreboot uses [Sphinx] documentation tool. We prefer the markdown format
|
||||
over reStructuredText so only embedded ReST is supported. Checkout the
|
||||
[Markdown Guide] for more information.
|
||||
|
||||
### option 1: Use the docker image
|
||||
|
||||
The easiest way to build the documentation is using a docker image.
|
||||
To build the image run the following in the base directory:
|
||||
|
||||
make -C util/docker/ doc.coreboot.org
|
||||
|
||||
Before building the documentation make sure the output directory is given
|
||||
the correct permissions before running docker.
|
||||
|
||||
mkdir -p Documentation/_build
|
||||
|
||||
To build the documentation:
|
||||
|
||||
make -C util/docker docker-build-docs
|
||||
|
||||
To have the documentation build and served over a web server live run:
|
||||
|
||||
make -C util/docker docker-livehtml-docs
|
||||
|
||||
On the host machine, open a browser to the address <http://0.0.0.0:8000>.
|
||||
|
||||
### option 2: Install Sphinx
|
||||
|
||||
Please follow this official [guide] to install sphinx.
|
||||
You will also need python-recommonmark for sphinx to be able to handle
|
||||
markdown documentation.
|
||||
|
||||
Since some Linux distributions don't package every needed sphinx extension,
|
||||
the installation via pip in a venv is recommended. You'll need these python3
|
||||
modules:
|
||||
|
||||
* sphinx
|
||||
* recommonmark
|
||||
* sphinx_rtd_theme
|
||||
* sphinxcontrib-ditaa
|
||||
|
||||
The following combination of versions has been tested: sphinx 2.3.1,
|
||||
recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
|
||||
|
||||
Now change into the `Documentation` folder in the coreboot directory and run
|
||||
this command in there
|
||||
|
||||
make sphinx
|
||||
|
||||
If no error occurs, you can find the generated HTML documentation in
|
||||
`Documentation/_build` now.
|
||||
|
||||
### Optional
|
||||
|
||||
Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly!
|
||||
|
||||
## Basic and simple rules
|
||||
|
||||
The following rules should be followed in order to get it at least reviewed
|
||||
on [review.coreboot.org].
|
||||
|
||||
Documentation:
|
||||
|
||||
1. Must be written in **markdown** with **embedded reStructuredText**
|
||||
format.
|
||||
2. Must be written in **English**.
|
||||
3. Must be placed into **Documentation/** directory subfolder.
|
||||
4. Should follow the same directory structure as **src/** when practical.
|
||||
5. Must be referenced from within other markdown files
|
||||
6. The commit must follow the [Gerrit Guidelines].
|
||||
7. Must have all **lowercase filenames**.
|
||||
8. Running text should have a visible width of about **72 chars**.
|
||||
9. Should not **duplicate** documentation, but reference it instead.
|
||||
10. Must not include the same picture in multiple markdown files.
|
||||
11. Images should be kept small. They should be under 700px in width, as
|
||||
the current theme doesn't allow bigger images.
|
||||
12. Shouldn't cover implementation details; for details, the code is the
|
||||
reference.
|
||||
|
||||
## Referencing markdown documents
|
||||
|
||||
Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.
|
||||
To reference documents use the TOC tree or inline RST code.
|
||||
|
||||
## Markdown and Tables
|
||||
|
||||
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
|
||||
+------------+------------+-----------+
|
||||
| Header 1 | Header 2 | Header 3 |
|
||||
+============+============+===========+
|
||||
| body row 1 | column 2 | column 3 |
|
||||
+------------+------------+-----------+
|
||||
| body row 2 | Cells may span columns.|
|
||||
+------------+------------+-----------+
|
||||
| body row 3 | Cells may | - Cells |
|
||||
+------------+ span rows. | - contain |
|
||||
| body row 4 | | - blocks. |
|
||||
+------------+------------+-----------+
|
||||
``` #just a code block is enough
|
||||
|
||||
## TocTree
|
||||
|
||||
To make sure that all documents are included into the final documentation, you
|
||||
must reference each document from at least one *toctree*. The *toctree* must
|
||||
only reference files in the same folder or in subfolders !
|
||||
To create a toctree, simply use a bullet list or numbered list with a single
|
||||
reference. References in regular text aren't considered as *toctree* .
|
||||
This feature is enabled by recommonmark's *enable_auto_toc_tree* .
|
||||
|
||||
**Example toctree:**
|
||||
|
||||
```
|
||||
* [Chapter 1](chapter1.md)
|
||||
* [Chapter 2](chapter2.md)
|
||||
* [Subchapter](sub/index.md)
|
||||
```
|
||||
|
||||
```
|
||||
1. [Chapter 1](chapter1.md)
|
||||
2. [Chapter 2](chapter2.md)
|
||||
```
|
||||
|
||||
If you do only reference the document, but do not include it in any toctree,
|
||||
you'll see the following warning:
|
||||
**WARNING: document isn't included in any toctree**
|
||||
|
||||
## CSV
|
||||
|
||||
You can import CSV files and let sphinx automatically convert them to human
|
||||
readable tables, using the following reStructuredText snipped:
|
||||
|
||||
```eval_rst
|
||||
.. csv-table::
|
||||
:header: "Key", "Value"
|
||||
:file: keyvalues.csv
|
||||
```
|
||||
|
||||
Of course this can only be done from a markdown file that is included in the
|
||||
TOC tree.
|
||||
|
||||
[coreboot]: https://coreboot.org
|
||||
[Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
|
||||
[sphinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
|
||||
[guide]: http://www.sphinx-doc.org/en/stable/install.html
|
||||
[Sphinx]: http://www.sphinx-doc.org/en/master/
|
||||
[Markdown Guide]: https://www.markdownguide.org/
|
||||
[Gerrit Guidelines]: gerrit_guidelines.md
|
||||
[review.coreboot.org]: https://review.coreboot.org
|
||||
@@ -1,64 +0,0 @@
|
||||
Display Panel Specifics
|
||||
=======================
|
||||
|
||||
Timing Parameters
|
||||
-----------------
|
||||
|
||||
From the binary file `edid` in the sys filesystem on Linux, the panel can be
|
||||
identified. The exact path may differ slightly. Here is an example:
|
||||
|
||||
```sh
|
||||
$ strings /sys/devices/pci0000:00/0000:00:02.0/drm/card0/card0-eDP-1/edid
|
||||
@0 5
|
||||
LG Display
|
||||
LP140WF3-SPD1
|
||||
```
|
||||
|
||||
To figure out the timing parameters, refer to the [Intel Programmer's Reference
|
||||
Manuals](https://01.org/linuxgraphics/documentation/hardware-specification-prms)
|
||||
and try to find the datasheet of the panel using the information from `edid`.
|
||||
In the example above, you would search for `LP140WF3-SPD1`. Find a table listing
|
||||
the power sequence timing parameters, which are usually named T[N] and also
|
||||
referenced in Intel's respective registers listing. You need the values for
|
||||
`PP_ON_DELAYS`, `PP_OFF_DELAYS` and `PP_DIVISOR` for your `devicetree.cb`:
|
||||
|
||||
```eval_rst
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Intel docs | devicetree.cb | eDP |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Power up delay | `gpu_panel_power_up_delay` | T3 |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Power on to backlight on | `gpu_panel_power_backlight_on_delay` | T7 |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Power Down delay | `gpu_panel_power_down_delay` | T10 |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Backlight off to power down | `gpu_panel_power_backlight_off_delay` | T9 |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
| Power Cycle Delay | `gpu_panel_power_cycle_delay` | T12 |
|
||||
+-----------------------------+---------------------------------------+-----+
|
||||
```
|
||||
|
||||
Intel GPU Tools and VBT
|
||||
-----------------------
|
||||
|
||||
The Intel GPU tools are in a package called either `intel-gpu-tools` or
|
||||
`igt-gpu-tools` in most distributions of Linux-based operating systems.
|
||||
In the coreboot `util/` directory, you can find `intelvbttool`.
|
||||
|
||||
From a running system, you can dump the register values directly:
|
||||
```sh
|
||||
$ intel_reg dump --all | grep PCH_PP
|
||||
PCH_PP_STATUS (0x000c7200): 0x80000008
|
||||
PCH_PP_CONTROL (0x000c7204): 0x00000007
|
||||
PCH_PP_ON_DELAYS (0x000c7208): 0x07d00001
|
||||
PCH_PP_OFF_DELAYS (0x000c720c): 0x01f40001
|
||||
PCH_PP_DIVISOR (0x000c7210): 0x0004af06
|
||||
```
|
||||
|
||||
You can obtain the timing values from a VBT (Video BIOS Table), which you can
|
||||
dump from a vendor UEFI image:
|
||||
```sh
|
||||
$ intel_vbt_decode data.vbt | grep T3
|
||||
Power Sequence: T3 2000 T7 10 T9 2000 T10 500 T12 5000
|
||||
T3 optimization: no
|
||||
```
|
||||
@@ -7,14 +7,13 @@ Introduction and Current State in coreboot
|
||||
*libgfxinit* is a library of full-featured graphics initialization
|
||||
(aka. modesetting) drivers. It's implemented in SPARK (a subset of
|
||||
Ada with formal verification features). While not restricted to in
|
||||
any way, it currently only supports Intel's integrated graphics
|
||||
controllers (GMA).
|
||||
any way, it currently only supports Intel's integrated gfx control-
|
||||
lers (GMA).
|
||||
|
||||
Currently, it supports the Intel Core i3/i5/i7 processor line, HDMI
|
||||
and DP on the Apollo Lake processors and everything but SDVO on G45
|
||||
and GM45 chipsets. At the time of writing, G45, GM45, everything
|
||||
from Arrandale to Coffee Lake, and Apollo Lake are verified to work
|
||||
within *coreboot*.
|
||||
Currently, it supports the Intel Core i3/i5/i7 processor line and
|
||||
will support HDMI and DP on the Atom successor Apollo Lake. At the
|
||||
time of writing, Sandy Bridge, Ivy Bridge, and Haswell are veri-
|
||||
fied to work within *coreboot*.
|
||||
|
||||
GMA: Framebuffer Configuration
|
||||
------------------------------
|
||||
@@ -49,36 +48,24 @@ follows:
|
||||
|
||||
* `lightup_ok`: returns whether the initialization succeeded `1` or
|
||||
failed `0`. Currently, only the case that no display
|
||||
could be found counts as failure. A failure at a
|
||||
later stage (e.g. failure to train a DP) is not
|
||||
propagated.
|
||||
could be found counts as failure. A failure at a la-
|
||||
ter stage (e.g. failure to train a DP) is not propa-
|
||||
gated.
|
||||
|
||||
GMA: Per Board Configuration
|
||||
----------------------------
|
||||
|
||||
In order to set up the display panel, see the
|
||||
[display panel-specific documentation](/gfx/display-panel.md).
|
||||
|
||||
There are a few Kconfig symbols to consider. To indicate that a
|
||||
board can initialize graphics through *libgfxinit*:
|
||||
|
||||
select MAINBOARD_HAS_LIBGFXINIT
|
||||
|
||||
Internal ports share some hardware blocks (e.g. backlight, panel
|
||||
power sequencer). Therefore, each system with an integrated panel
|
||||
should set `GFX_GMA_PANEL_1_PORT` to the respective port, e.g.:
|
||||
power sequencer). Therefore, each board has to select either eDP
|
||||
or LVDS as the internal port, if any:
|
||||
|
||||
config GFX_GMA_PANEL_1_PORT
|
||||
default "DP3"
|
||||
|
||||
For the most common cases, LVDS and eDP, exists a shorthand, one
|
||||
can select either:
|
||||
|
||||
select GFX_GMA_PANEL_1_ON_EDP # the default, or
|
||||
select GFX_GMA_PANEL_1_ON_LVDS
|
||||
|
||||
Some newer chips feature a second block of panel control logic.
|
||||
For this, `GFX_GMA_PANEL_2_PORT` can be set.
|
||||
select GFX_GMA_INTERNAL_IS_EDP # the default, or
|
||||
select GFX_GMA_INTERNAL_IS_LVDS
|
||||
|
||||
Boards with a DVI-I connector share the DDC (I2C) pins for both
|
||||
analog and digital displays. In this case, *libgfxinit* needs to
|
||||
@@ -88,29 +75,9 @@ know through which interface the EDID can be queried:
|
||||
select GFX_GMA_ANALOG_I2C_HDMI_C # or
|
||||
select GFX_GMA_ANALOG_I2C_HDMI_D
|
||||
|
||||
*libgfxinit* needs to know which ports are implemented on a board
|
||||
and should be probed for displays. There are two mechanisms to
|
||||
constrain the list of ports to probe, 1. port presence straps on
|
||||
the mainboard, and 2. a list of ports provided by *coreboot* (see
|
||||
below).
|
||||
|
||||
Presence straps are configured via the state of certains pins of
|
||||
the chipset at reset time. They are documented in the chipset's
|
||||
datasheets. By default, *libgfxinit* honors these straps for
|
||||
safety. However, some boards don't implement the straps correctly.
|
||||
If ports are not strapped as implemented by error, one can select
|
||||
an option to ignore the straps:
|
||||
|
||||
select GFX_GMA_IGNORE_PRESENCE_STRAPS
|
||||
|
||||
In the opposite case, that ports are strapped as implemented,
|
||||
but are actually unconnected, one has to make sure that the
|
||||
list of ports in *coreboot* omits them.
|
||||
|
||||
The mapping between the physical ports and these entries depends on
|
||||
the hardware implementation and can be recovered by testing or
|
||||
studying the output of `intelvbttool` or `intel_vbt_decode`.
|
||||
Each board has to implement the package `GMA.Mainboard` with a list:
|
||||
Beside Kconfig options, *libgfxinit* needs to know which ports are
|
||||
implemented on a board and should be probed for displays. Each
|
||||
board has to implement the package `GMA.Mainboard` with a list:
|
||||
|
||||
ports : HW.GFX.GMA.Display_Probing.Port_List;
|
||||
|
||||
@@ -122,8 +89,7 @@ You can select from the following Ports:
|
||||
|
||||
type Port_Type is
|
||||
(Disabled, -- optionally terminates the list
|
||||
LVDS,
|
||||
eDP,
|
||||
Internal, -- either eDP or LVDS as selected in Kconfig
|
||||
DP1,
|
||||
DP2,
|
||||
DP3,
|
||||
@@ -139,7 +105,8 @@ both DPx and HDMIx should be listed.
|
||||
|
||||
A good example is the mainboard Kontron/KTQM77, it features two
|
||||
DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
|
||||
eDP and LVDS. It defines `ports` as follows:
|
||||
eDP and LVDS. Due to the constraints mentioned above, only one of
|
||||
eDP and LVDS can be enabled. It defines `ports` as follows:
|
||||
|
||||
ports : constant Port_List :=
|
||||
(DP2,
|
||||
@@ -148,8 +115,7 @@ eDP and LVDS. It defines `ports` as follows:
|
||||
HDMI2,
|
||||
HDMI3,
|
||||
Analog,
|
||||
LVDS,
|
||||
eDP,
|
||||
Internal,
|
||||
others => Disabled);
|
||||
|
||||
The `GMA.gfxinit()` procedure probes for display EDIDs in the
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
# ifdtool
|
||||
|
||||
Contents:
|
||||
|
||||
* [Intel IFD Binary Extraction](binary_extraction.md)
|
||||
* [IFD Layout](layout.md)
|
||||
@@ -1,78 +0,0 @@
|
||||
# IFD Layout
|
||||
|
||||
A coreboot image for an Intel SoC contains two separate definitions of the
|
||||
layout of the flash. The Intel Flash Descriptor (IFD) which defines offsets and
|
||||
sizes of various regions of flash and the [coreboot FMAP](../lib/flashmap.md).
|
||||
|
||||
The FMAP should define all of the of the regions defined by the IFD to ensure
|
||||
that those regions are accounted for by coreboot and will not be accidentally
|
||||
modified.
|
||||
|
||||
## IFD mapping
|
||||
|
||||
The names of the IFD regions in the FMAP should follow the convention of
|
||||
starting with the prefix `SI_` which stands for `silicon initialization` as a
|
||||
way to categorize anything required by the SoC but not provided by coreboot.
|
||||
|
||||
```eval_rst
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| IFD Region | IFD Region name | FMAP Name | Notes |
|
||||
| index | | | |
|
||||
+============+==================+===========+===========================================+
|
||||
| 0 | Flash Descriptor | SI_DESC | Always the top 4KB of flash |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| 1 | BIOS | SI_BIOS | This is the region that contains coreboot |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| 2 | Intel ME | SI_ME | |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| 3 | Gigabit Ethernet | SI_GBE | |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| 4 | Platform Data | SI_PDR | |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
| 8 | EC Firmware | SI_EC | Most Chrome OS devices do not use this |
|
||||
| | | | region; EC firmware is stored in BIOS |
|
||||
| | | | region of flash |
|
||||
+------------+------------------+-----------+-------------------------------------------+
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
The ifdtool can be used to manipulate a firmware image with a IFD. This tool
|
||||
will not take into account the FMAP while modifying the image which can lead to
|
||||
unexpected and hard to debug issues with the firmware image. For example if the
|
||||
ME region is defined at 6 MB in the IFD but the FMAP only allocates 4 MB for the
|
||||
ME, then when the ME is added by the ifdtool 6 MB will be written which could
|
||||
overwrite 2 MB of the BIOS.
|
||||
|
||||
In order to validate that the FMAP and the IFD are compatible the ifdtool
|
||||
provides --validate (-t) option. `ifdtool -t` will read both the IFD and the
|
||||
FMAP in the image and for every non empty region in the IFD if that region is
|
||||
defined in the FMAP but the offset or size is different then the tool will
|
||||
return an error.
|
||||
|
||||
Example:
|
||||
|
||||
```console
|
||||
foo@bar:~$ ifdtool -t bad_image.bin
|
||||
Region mismatch between bios and SI_BIOS
|
||||
Descriptor region bios:
|
||||
offset: 0x00400000
|
||||
length: 0x01c00000
|
||||
FMAP area SI_BIOS:
|
||||
offset: 0x00800000
|
||||
length: 0x01800000
|
||||
Region mismatch between me and SI_ME
|
||||
Descriptor region me:
|
||||
offset: 0x00103000
|
||||
length: 0x002f9000
|
||||
FMAP area SI_ME:
|
||||
offset: 0x00103000
|
||||
length: 0x006f9000
|
||||
Region mismatch between pd and SI_PDR
|
||||
Descriptor region pd:
|
||||
offset: 0x003fc000
|
||||
length: 0x00004000
|
||||
FMAP area SI_PDR:
|
||||
offset: 0x007fc000
|
||||
length: 0x00004000
|
||||
```
|
||||
@@ -1,191 +1,21 @@
|
||||
# Welcome to the coreboot documentation
|
||||
Welcome to coreboot's documentation!
|
||||
====================================
|
||||
|
||||
This is the developer documentation for [coreboot](https://coreboot.org).
|
||||
It is built from Markdown files in the
|
||||
[Documentation](https://review.coreboot.org/cgit/coreboot.git/tree/Documentation)
|
||||
directory in the source code.
|
||||
|
||||
## Purpose of coreboot
|
||||
|
||||
coreboot is a project to develop open source boot firmware for various
|
||||
architectures. Its design philosophy is to do the bare minimum necessary to
|
||||
ensure that hardware is usable and then pass control to a different program
|
||||
called the _payload_.
|
||||
|
||||
### Separation of concerns
|
||||
|
||||
The payload can then provide user interfaces, file system drivers,
|
||||
various policies etc. to load the OS. Through this separation of concerns
|
||||
coreboot maximizes reusability of the complicated and fundamental hardware
|
||||
initialization routines across many different use cases, no matter if
|
||||
they provide standard interfaces or entirely custom boot flows.
|
||||
|
||||
Popular [payloads](payloads.md) in use with coreboot are SeaBIOS,
|
||||
which provides PCBIOS services, Tianocore, which provides UEFI services,
|
||||
GRUB2, the bootloader used by many Linux distributions, or depthcharge,
|
||||
a custom boot loader used on Chromebooks.
|
||||
|
||||
### No resident services (if possible)
|
||||
|
||||
Ideally coreboot completely hands over control to the payload with no
|
||||
piece of coreboot remaining resident in the system, or even available
|
||||
for callback. Given the reality of contemporary computer design,
|
||||
there's often a small piece that survives for the whole runtime of
|
||||
the computer. It runs in a highly privileged CPU mode (e.g. SMM on x86)
|
||||
and provides some limited amount of services to the OS. But here, too,
|
||||
coreboot aims to keep everything at the minimum possible, both in scope
|
||||
(e.g. services provided) and code size.
|
||||
|
||||
### No specification of its own
|
||||
|
||||
coreboot uses a very minimal interface to the payload, and otherwise
|
||||
doesn't impose any standards on the ecosystem. This is made possible by
|
||||
separating out concerns (interfaces and resident services are delegated
|
||||
to the payload), but it's also a value that is deeply ingrained in the
|
||||
project. We fearlessly rip out parts of the architecture and remodel it
|
||||
when a better way of doing the same was identified.
|
||||
|
||||
### One tree for everything
|
||||
|
||||
Another difference to various other firmware projects is that we try
|
||||
to avoid fragmentation: the traditional development model of firmware
|
||||
is one of "set and forget" in which some code base is copied, adapted
|
||||
for the purpose at hands, shipped and only touched again if there's an
|
||||
important fix to do.
|
||||
|
||||
All newer development happens on another copy of some code base without
|
||||
flowing back to any older copy, and so normally there's a huge amount
|
||||
of fragmentation.
|
||||
|
||||
In coreboot, we try to keep everything in a single source tree, and
|
||||
lift up older devices when we change something fundamentally. That way,
|
||||
new and old devices benefit alike from new development in the common parts.
|
||||
|
||||
There's a downside to that: Some devices might have no maintainer anymore
|
||||
who could ensure that coreboot is still functional for them after a big
|
||||
rework, or maybe a rework even requires knowledge that doesn't exist
|
||||
anymore within the project (for example because the developer moved on
|
||||
to do something else).
|
||||
|
||||
In this case, we announce the deprecation of the device and defer the big
|
||||
rework until the deprecation period passed, typically 6-12 months. This
|
||||
gives interested developers a chance to step in and bring devices up to
|
||||
latest standards.
|
||||
|
||||
While without this deprecation mechanism we could inflate the number
|
||||
of supported devices (probably 300+), only a tiny fraction of them
|
||||
would even work, which helps nobody.
|
||||
|
||||
## Scope of the coreboot project
|
||||
|
||||
coreboot as a project is closer to the Linux kernel than to most
|
||||
user level programs. One place where this becomes apparent is the
|
||||
distribution mechanism: The project itself only provides source code
|
||||
and does not ship ready-to-install coreboot-based firmware binaries.
|
||||
|
||||
What the project distributes, even if - strictly speaking - it's not
|
||||
part of the project, is a collection of vendor binaries (that we call
|
||||
"blobs") that are redistributable. They cover the parts of hardware init
|
||||
that we haven't managed to open up, and while some hardware requires them,
|
||||
there's still hardware that can boot without any such binary components.
|
||||
|
||||
The build system can integrate them into the build automatically if
|
||||
required, but that requires explicit opt-in and downloads a separate
|
||||
repository to ensure that the distinction remains clear.
|
||||
|
||||
There are various [distributions](distributions.md), some shipping
|
||||
coreboot with their hardware (e.g. Purism or Chromebooks), others
|
||||
providing after-market images for various devices (e.g. Libreboot,
|
||||
MrChromebox).
|
||||
|
||||
If you want to use coreboot on your system, that's great!
|
||||
|
||||
Please note that the infrastructure around coreboot.org is built for
|
||||
development purposes. We gladly help out users through our communication
|
||||
channels, but we also expect a "firmware developer mindset": If compiling
|
||||
your own firmware and, at some point, recovering from a bad flash by
|
||||
hooking wires onto chips in your computer sounds scary to you, you're
|
||||
right, as it is.
|
||||
|
||||
If that's _way_ beyond your comfort zone, consider looking into the
|
||||
various distributions, as they typically provide pre-tested binaries
|
||||
which massively reduces the risk that the binary you write to flash is
|
||||
one that won't boot the system (with the consequence that to get it to work
|
||||
again, you'll need to attach various tools to various chips)
|
||||
|
||||
## The coreboot community
|
||||
|
||||
If you're interested in getting your hands dirty (incl. potentially wiring
|
||||
up an external flasher to your computer), you've come to the right place!
|
||||
|
||||
We have various [forums](community/forums.md) where we discuss and coordinate
|
||||
our activities, review patches, and help out each other. To
|
||||
help promote a positive atmosphere, we established a [Code of
|
||||
Conduct](community/code_of_conduct.md). We invested a lot of time
|
||||
to balance it out, so please keep it in mind when engaging with the
|
||||
coreboot community.
|
||||
|
||||
Every now and then, coreboot is present in one way or another at
|
||||
[conferences](community/conferences.md). If you're around, come and
|
||||
say hello!
|
||||
|
||||
## Getting the source code
|
||||
|
||||
coreboot is primarily developed in the
|
||||
[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 `master` branch in the repository functional
|
||||
for all hardware we support. So far, the only guarantee we can make is
|
||||
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
|
||||
get better in that respect, e.g. by setting up boot testing facilities. This
|
||||
is obviously more complex than regular integration testing, so progress
|
||||
is slow.
|
||||
|
||||
### What our releases mean
|
||||
|
||||
We also schedule two source code releases every year, around April and
|
||||
October. These releases see some very limited testing and mostly serve
|
||||
as synchronization points for deprecation notices and for other projects
|
||||
such as external distributions.
|
||||
|
||||
This approach and terminology differs somewhat from how other projects handle
|
||||
releases where releases are well-tested artifacts and the development
|
||||
repository tends to be unstable. The "rolling release" model of some projects,
|
||||
for example OpenBSD, is probably the closest cousin of our approach.
|
||||
|
||||
Contents:
|
||||
|
||||
* [Getting Started](getting_started/index.md)
|
||||
* [Tutorial](tutorial/index.md)
|
||||
* [Coding Style](coding_style.md)
|
||||
* [Project Ideas](contributing/project_ideas.md)
|
||||
* [Documentation Ideas](contributing/documentation_ideas.md)
|
||||
* [Code of Conduct](community/code_of_conduct.md)
|
||||
* [Language style](community/language_style.md)
|
||||
* [Community forums](community/forums.md)
|
||||
* [Project services](community/services.md)
|
||||
* [coreboot at conferences](community/conferences.md)
|
||||
* [Payloads](payloads.md)
|
||||
* [Distributions](distributions.md)
|
||||
* [Technotes](technotes/index.md)
|
||||
* [ACPI](acpi/index.md)
|
||||
* [Lesson 2: Submitting a patch to coreboot.org](Lesson2.md)
|
||||
* [Gerrit Etiquette and Guidelines](gerrit_guidelines.md)
|
||||
* [coreboot's build system](build_system.md)
|
||||
* [Kconfig in coreboot](core/Kconfig.md)
|
||||
* [Use of git submodules in coreboot](submodules.md)
|
||||
* [Timestamps](timestamp.md)
|
||||
* [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
|
||||
* [ABI data consumption](abi-data-consumption.md)
|
||||
* [GPIO toggling in ACPI AML](acpi/gpio.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)
|
||||
* [Security](security/index.md)
|
||||
* [SuperIO](superio/index.md)
|
||||
* [Vendorcode](vendorcode/index.md)
|
||||
* [Utilities](util.md)
|
||||
* [Release notes for past releases](releases/index.md)
|
||||
* [Flashing firmware tutorial](flash_tutorial/index.md)
|
||||
* [Sandy Bridge Raminit](Intel/NativeRaminit/Sandybridge.md)
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user