coreboot-gerrit November 2016

coreboot-gerrit@coreboot.org

1 participants
1666 discussions

Patch merged into coreboot/master: vendorcode/amd: Update Kconfig and makefiles for 00670F00
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 21e5dd8a8503734e8f1199e5de0e3da1d84e3081 Author: Marc Jones <marcj303(a)gmail.com> Date: Tue Sep 20 20:32:47 2016 -0600 vendorcode/amd: Update Kconfig and makefiles for 00670F00 Add Stoney specific code subtree and fix Makefles and Kconfig files. Original-Author: Charles Marslett <charles(a)scarlettechnologies.com> Original-Signed-off-by: Marc Jones <marcj303(a)gmail.com> Original-Reviewed-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> Original-Tested-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> (cherry picked from commit 51a187a3d08a425ef0cc141a7ddc49a70ac931b1) Change-Id: I13c6b08c780e7bd2abd0fabbde1a89686132f65c Signed-off-by: Marc Jones <marcj303(a)gmail.com> Reviewed-on: https://review.coreboot.org/17196 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth <martinroth(a)google.com> See https://review.coreboot.org/17196 for details. -gerrit

1 0

Patch merged into coreboot/master: vendorcode/amd: Modify 0067F00 for binaryPI
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit f3093883f7336054f344072c5b086998dc5f72c2 Author: Marshall Dawson <marshalldawson3rd(a)gmail.com> Date: Sat Oct 15 09:45:44 2016 -0600 vendorcode/amd: Modify 0067F00 for binaryPI Make changes to the vendorcode files that allow them to work with the binaryPI. This fixes various compile issues and establishes a common calling convention between coreboot and AGESA. Original-Signed-off-by: Marc Jones <marcj303(a)gmail.com> Original-Signed-off-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> (cherry picked from commit f7ea2785d70bd6813b5b4d315b064802251d9557) Change-Id: Ie36228476a9dbd7b83f95828ca9c7252cecd8ec8 Signed-off-by: Marc Jones <marcj303(a)gmail.com> Reviewed-on: https://review.coreboot.org/17195 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth <martinroth(a)google.com> See https://review.coreboot.org/17195 for details. -gerrit

1 0

Patch merged into coreboot/master: vendorcode/amd: Copy 00670F00 files from PI package
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit a04006513008ef72a863bc0eb04e6d4f729ca8ab Author: Marshall Dawson <marshalldawson3rd(a)gmail.com> Date: Sat Oct 15 09:20:43 2016 -0600 vendorcode/amd: Copy 00670F00 files from PI package Make exact copies of the AGESA files from the Stoney PI package replacing existing versions. Change the license text and fix up misc. whitespace. This will facilitate the review of binaryPI changes in the vendorcode directory. Original-Signed-off-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> Original-Reviewed-by: Marc Jones <marcj303(a)gmail.com> (cherry picked from commit 1097249585ab76fab59dcfbf8e7a419f34fcfcb6) Change-Id: I9951df58aeab2d533efc0a837ce35f343ff28d7c Signed-off-by: Marc Jones <marcj303(a)gmail.com> Reviewed-on: https://review.coreboot.org/17194 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth <martinroth(a)google.com> See https://review.coreboot.org/17194 for details. -gerrit

1 0

Patch merged into coreboot/master: vendorcode/amd: Copy 00660F01 directory to 00670F00
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 9ef6e52353dbbcfac727e0207dbbcc07dfb75d47 Author: Marc Jones <marcj303(a)gmail.com> Date: Tue Sep 20 20:16:20 2016 -0600 vendorcode/amd: Copy 00660F01 directory to 00670F00 Prepare for new 00670FF00 support. Original-Signed-off-by: Marc Jones <marcj303(a)gmail.com> Original-Reviewed-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> Original-Tested-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> (cherry picked from commit ca53cac5c847c55e56ad6f5feb382c04f33ae77a) Change-Id: Ib48b1611bf70ec302c50f6e07bd2b3d9b09e0a24 Signed-off-by: Marc Jones <marcj303(a)gmail.com> Reviewed-on: https://review.coreboot.org/17193 Tested-by: build bot (Jenkins) Reviewed-by: Martin Roth <martinroth(a)google.com> See https://review.coreboot.org/17193 for details. -gerrit

1 0

Patch merged into coreboot/master: arch/x86/acpigen: Add OperationRegion & Field method
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 8535c66873e8853bcca3031df4e49c472aafda14 Author: Naresh G Solanki <naresh.solanki(a)intel.com> Date: Tue Oct 25 00:51:24 2016 +0530 arch/x86/acpigen: Add OperationRegion & Field method Add acpigen_write_opregion that generates ACPI AML code for OperationRegion, region name, region space, region length & region size are inputs. Add acpigen_write_field that generates ACPI AML code for Field. Operation region name & field list are inputs. Change-Id: I578834217d39aa3b0d409eb8ba4b5f7a31969fa8 Signed-off-by: Naresh G Solanki <naresh.solanki(a)intel.com> Reviewed-on: https://review.coreboot.org/17113 Reviewed-by: Furquan Shaikh <furquan(a)google.com> Tested-by: build bot (Jenkins) See https://review.coreboot.org/17113 for details. -gerrit

1 0

Patch set updated for coreboot: Documentation: WIP refactor existing documentation
by Martin Roth 07 Nov '16

07 Nov '16

Martin Roth (martinroth(a)google.com) just uploaded a new patch set to gerrit, which you can find at https://review.coreboot.org/16853 -gerrit commit bd771c04253d637839bbd048b5308111b10f2402 Author: Philipp Deppenwiese <zaolin(a)das-labor.org> Date: Sun Oct 2 23:20:14 2016 +0200 Documentation: WIP refactor existing documentation Change-Id: I9120da6bd24783872c63087139f8730771dde9ad Signed-off-by: Philipp Deppenwiese <zaolin(a)das-labor.org> --- Documentation/AMD-S3.txt | 153 -- Documentation/CorebootBuildingGuide.tex | 671 -------- Documentation/Doxyfile.coreboot | 1639 -------------------- Documentation/Doxyfile.coreboot_simple | 258 --- Documentation/Intel/Board/Galileo_checklist.html | 162 -- Documentation/Intel/Board/board.html | 240 --- Documentation/Intel/Board/galileo.html | 114 -- Documentation/Intel/SoC/quark.html | 220 --- Documentation/Intel/SoC/soc.html | 734 --------- Documentation/Intel/development.html | 377 ----- Documentation/Intel/fsp1_1.html | 77 - Documentation/Intel/index.html | 128 -- Documentation/Kconfig.tex | 480 ------ Documentation/Makefile | 70 - Documentation/POSTCODES | 25 - Documentation/README | 8 + Documentation/RFC/chip.tex | 266 ---- Documentation/RFC/config.tex | 290 ---- Documentation/abi-data-consumption.txt | 22 - Documentation/beginverbatim.tex | 1 - Documentation/build_system.md | 86 - Documentation/cbfs.txt | 421 ----- Documentation/codeflow.svg | 234 --- Documentation/core/00-index.md | 11 + Documentation/core/10-build_system.md | 98 ++ Documentation/core/20-gerrit_guidelines.md | 125 ++ Documentation/core/30-submodules.md | 46 + Documentation/coreboot_logo.png | Bin 2236 -> 0 bytes Documentation/endverbatim.tex | 1 - Documentation/gcov.txt | 227 --- Documentation/gerrit_guidelines.md | 277 ---- Documentation/hypertransport.svg | 59 - Documentation/index.html | 26 - Documentation/index.md | 6 + Documentation/intel/00-index.md | 11 + Documentation/intel/10-overview.md | 187 +++ Documentation/intel/20-development.md | 488 ++++++ Documentation/intel/30-fsp1_1.md | 60 + Documentation/intel/40-boards.md | 163 ++ Documentation/intel/50-soc.md | 402 +++++ Documentation/intel/boards/galileo/00-index.md | 93 ++ Documentation/intel/boards/galileo/10-checklist.md | 1361 ++++++++++++++++ Documentation/intel/soc/quark/00-index.md | 144 ++ Documentation/mainboard_io_trap_handler_sample.c | 51 - Documentation/submodules.txt | 46 - Documentation/timestamp.md | 200 --- 46 files changed, 3203 insertions(+), 7555 deletions(-) diff --git a/Documentation/AMD-S3.txt b/Documentation/AMD-S3.txt deleted file mode 100644 index 48d4c8f..0000000 --- a/Documentation/AMD-S3.txt +++ /dev/null @@ -1,153 +0,0 @@ - _____ ____ _____ ______ ____ ____ ____ _______ - / ____/ __ \| __ \| ____| _ \ / __ \ / __ \__ __| - | | | | | | |__) | |__ | |_) | | | | | | | | | - | | | | | | _ /| __| | _ <| | | | | | | | | - | |___| |__| | | \ \| |____| |_) | |__| | |__| | | | - \_____\____/|_| \_\______|____/ \____/ \____/ |_| - - __ __ _____ _____ ____ - /\ | \/ | __ \ / ____| |___ \ - / \ | \ / | | | | | (___ __) | - / /\ \ | |\/| | | | | \___ \ |__ < - / ____ \| | | | |__| | ____) | ___) | - /_/ \_\_| |_|_____/ |_____/ |____/ - - - S3 in Coreboot (V 1.2) ----------------------------------------- - Zheng Bao - <zheng.bao(a)amd.com> - <fishbaozi(a)gmail.com> - -Introduction -============ -This document is about how the feature S3 is implemented on coreboot, -specifically on AMD platform. This topic deals with ACPI spec, hardware, -BIOS, OS. We try to help coreboot users to realize their own S3. - -S3 in a nutshell -================ -The S3 sleeping state is a low wake latency sleeping state where all -system context is lost except system memory. [1]. S3 is a ACPI -definition. -To enter S3, write 3 in SLP_TYPx and set the SLP_EN bit (See ACPI -registers). But if you do that, board can not resume at where it -sleeps, because you don't save the context. More often than not, we -make the board go into S3 by the tools which OSes provide. For -windows, click Start->sleep. For linux, some distribution provide a -tools called pm-suspend, which can make the system goto S3. If -pm-suspend is not available, we can run "echo mem > /sys/power/state", -but this way may not save all the needed context. -In S3 state, the power is off. So when the power button is pressed, -BIOS runs as it does in cold boot. If BIOS didn't detect whether -board boots or resumes, it would go the same way as boot. It is not -what we expect. BIOS detects the SLP_TYPx. If it is 3, it means BIOS -are waking up. -BIOS is responsible for restore the machine state as it is before -sleep. It needs restore the memory controller, not overwriting memory -which is not marked as reserved. For the peripheral which loses its -registers, BIOS needs to write the original value. -When everything is done, BIOS needs to find out the wakeup vector -provided by OSes and jump there. OSes also have work to do. We can go -to linux kernel or some other open source projects to find out how they -handle S3 resume. - -ACPI registers -============== -ACPI specification defines a group of registers. OSes handle all these -registers to read and write status to all the platform. -On AMD platform, these registers are provided by southbridge. For -example, Hudson uses PMIO 60:6F to define ACPI registers. -OSes don't have any specific driver to know where these registers -are. BIOS has the responsibility to allocated the IO resources and -write all these address to FADT, a ACPI defined table. - -Memory Layout -============= -Restoring memory is the most important job done by BIOS. When the -power is off, the memory is maintained by standby power. BIOS need to -make sure that when flow goes to OS, everything in memory should be -the same as it was. - -The chip vendor will provide a way, or code, to wake up the memory -from sleeping. In AGESA 2008 arch, it is called AmdInitResume. - -The BIOS itself needs some memory to run. Either, BIOS marks the erea -as reserved in e820, or BIOS saves the content into reserved space. - -Here is the address Map for S3 Resume. Assumingly the total memory is 1GB. -00000000 --- 00100000 BIOS Reserved area. -00100000 --- 00200000 Free -00200000 --- 01000000 Coreboot ramstage area. -01000000 --- 2e160000 Free -2e160000 --- 2e170000 ACPI table -2e170000 --- 2ef70000 OSRAM -2ef70000 --- 2efe0000 Stack in highmem -2efe0000 --- 2f000000 heap in highmem -2f000000 TOM - -AMD requirements in S3 -====================== -Chip vendor like AMD will provide bunch of routines to restore the -board.[2] - * AmdS3Save: It is called in cold boot, save required register into - non-volatile storage. Currently, we use SPI flash to store the data. - * AmdInitResume: Restore the memory controller. - * AmdS3LateRestore: Called after AmdInitResume, restore other - register that memory. - * (SouthBridge)InitS3EarlyRestore, (SouthBridge)InitS3LateRestore: - Provided by Southbridge vendor code. Early is called before PCI - enumeration, and Late is called after that. - -Lifecycle of booting, sleeping and waking Coreboot and Ubuntu -============================================================= -1. Cold boot. -For a system with S3 feature, the BIOS needs to save some data to -non-volatile storage at cold boot stage. What data need to be save are -provided by AmdS3Save. After the wrapper calls the AmdS3Save, it gets -the VolatileStorage and NvStorage, which are where the data are -located. It is the wrappers's responsibility to save the data.[3][4] -Currently, the wrappers allocate a CBFS modules in BIOS image. To do -that, the wrapper needs to have the ability to write flash chips. It -is not as comprehensive as flashrom. But for the SST chip on Parmer, -MX chip on Thather, coreboot works well.[5] - -2. OS goes in S3. -For Linux, besides the kernel needs to do some saving, most distributions -run some scripts. For Ubuntu, scripts are located at /usr/lib/pm-utils/sleep.d. - # ls /usr/lib/pm-utils/sleep.d - 000kernel-change 49bluetooth 90clock 95led - 00logging 55NetworkManager 94cpufreq 98video-quirk-db-handler - 00powersave 60_wpa_supplicant 95anacron 99video - 01PulseAudio 75modules 95hdparm-apm -The script with lower prefix runs before the one with higher prefix. -99video is the last one. -Those scripts have hooks called hibernate, suspend, thaw, resume. For -each script, suspend is called when system sleeps and wakeup is called -when system wakeups. - -3. Firmware detects S3 wakeup -As we mentioned, Firmware detects the SLP_TYPx to find out if the board -wakes up. In romstage.c, AmdInitReset and AmdInitEarly are called -as they are during cold boot. AmdInitResume and AmdS3LateRestore are -called only during resume. For whole ramstage, Coreboot goes through -almost the same way as cold boot, other than not calling the AmdInitMid, -AmdInitLate and AmdS3Save, and restoring all the MTRRs. -At last step of coreboot stage, coreboot finds out the wakeup vector in FADT, -written by OS, and jump. - -4. OS resumes. -When Linux resumes, all the sleeping scripts call their resume -hooks. If we are more lucky, all the scripts can go through. More -chances that the 99video hangs or fails to get the display -back. Sometimes it can fixed if CONFIG_S3_VGA_ROM_RUN is unset in -Coreboot/Kconfig. That needs more troubleshooting. - - -Reference -========= -[1] ACPI40a, http://www.acpi.info/spec40a.htm -[2] Coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/ -[3] Coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c -[4] Coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c -[5] Coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c diff --git a/Documentation/CorebootBuildingGuide.tex b/Documentation/CorebootBuildingGuide.tex deleted file mode 100644 index eb4dfd2..0000000 --- a/Documentation/CorebootBuildingGuide.tex +++ /dev/null @@ -1,671 +0,0 @@ -% -% This document is released under the GPL -% Initially written by Stefan Reinauer, <stepan(a)coresystems.de> -% - -\documentclass[titlepage,12pt]{article} -\usepackage{a4} -\usepackage{graphicx} -\usepackage{epsfig} -\usepackage{epstopdf} -\usepackage{url} -\usepackage{color} -% \usepackage{geometry} -\usepackage[pdftex]{hyperref} -% \usepackage{makeidx} -% \makeindex -% \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm} - -\hypersetup{ - urlbordercolor={1 1 1}, - menubordercolor={1 1 1}, - linkbordercolor={1 1 1}, - colorlinks=false, - % pdfpagemode=None, % PDF-Viewer starts without TOC - % pdfstartview=FitH, - pdftitle={Coreboot Porting Guide}, - pdfauthor={Zheng Bao}, - pdfsubject={coreboot configuration and build process}, - pdfkeywords={coreboot, AMD, configuration, Build} -} - -\setlength{\parindent}{0pt} -\setlength{\hoffset}{0pt} - -\title{Coreboot from Scratch} -\author{Stefan Reinauer $<$stepan(a)coresystems.de$>$\and Zheng Bao $<$zheng.bao(a)amd.com$>$} -\date{Dec 4th, 2013} - -\begin{document} - -\maketitle - -\thispagestyle{empty} - -\tableofcontents - -\newpage - -\section{What is Coreboot} -coreboot aims to replace the normal BIOS found on x86, AMD64, PPC, -Alpha, and other machines with a Linux kernel that can boot Linux from a cold -start. The startup code of an average coreboot port is about 500 lines of -assembly and 5000 lines of C. It executes 16 instructions to get into 32bit -protected mode and then performs DRAM and other hardware initializations -required before Linux can take over. - -The projects primary motivation initially was maintenance of large -clusters. Not surprisingly interest and contributions have come from -people with varying backgrounds. Nowadays a large and growing number of -Systems can be booted with coreboot, including embedded systems, -Desktop PCs and Servers. - -This document is used to build, modify, and port the CoreBoot code -base on the AMD platform. - - -\section{Changes} - - \begin{itemize} - \item 2013/12/20 Add Git, Gerrit, toolchains building. - \item 2009/04/19 replace LinuxBIOS with coreboot - \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs(a)winternet.com$>$ - \item 2004/02/10 ACPI and option ROM updates - \item 2003/11/18 initial release - \end{itemize} - -% -% Build Requirements -% - -\section{Build Requirements} -To build coreboot for AMD64 from the sources you need a recent Linux. -SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD, -NetBSD are known to work fine. - -To build the toolchain, you need following host compilers: - - \begin{itemize} - \item GNUtar - \item GNUpatch - \item GNUmake - \item GCC - \item binutils - \item bison - \item flex - \item m4 - \item wget - \end{itemize} - -Besides the tools above, after the toolchains are built, you also need the following -tools to build the source. - - \begin{itemize} - \item git: Get the source code from repository - \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig - \item python: Optional for gdb. - \item perl: Optional for gdb. - \end{itemize} - -% -% Getting Coreboot -% - -\section{Getting Coreboot} -The latest coreboot sources are available via GIT. -For users who doesn't need to change and commit the code: -{ \small -\begin{verbatim} -$ git clone http://review.coreboot.org/p/coreboot -\end{verbatim} -} -For developers, you need to get a gerrit account which you can register -at \url{http://review.coreboot.org}. Please refer section ~\ref{sec:gerrit} -{ \small -\begin{verbatim} -$ git clone ssh://<username>@review.coreboot.org:29418/coreboot -$ git clone http://[<username>:<password>@]review.coreboot.org/coreboot.git -\end{verbatim} -} - -Checks out a sub-repository in the 3rdparty directory. -{ \small -\begin{verbatim} -$ git submodule update --init --checkout -\end{verbatim} -} - -% -% Building the toolchain -% - -\section{Building the toolchain} -Coreboot recommends and guarantees the toolchain integrated with Coreboot. -Linux distributions usually modify their compilers in ways incompatible with Coreboot. - -{ \small -\begin{verbatim} -$ cd coreboot -$ make crossgcc -\end{verbatim} -} - -or - -{ \small -\begin{verbatim} -$ cd util/crossgcc -$ buildgcc -\end{verbatim} -} - -The buildgcc will try to get packages from website. You need to make sure you can -get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs. - -{ \small -\textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)} - -Target arch is now i386-elf - -Will skip GDB ... ok - -Downloading tar balls ... - - * gmp-5.1.2.tar.bz2 (cached) - - * mpfr-3.1.2.tar.bz2 (cached) - - * mpc-1.0.1.tar.gz (cached) - - * libelf-0.8.13.tar.gz (cached) - - * gcc-4.7.3.tar.bz2 (cached) - - * binutils-2.23.2.tar.bz2 (cached) - - * acpica-unix-20130626.tar.gz (cached) - -Downloaded tar balls ... \textcolor {green}{ok} - -Unpacking and patching ... - - * gmp-5.1.2.tar.bz2 - - * mpfr-3.1.2.tar.bz2 - - * mpc-1.0.1.tar.gz - - * libelf-0.8.13.tar.gz - - * gcc-4.7.3.tar.bz2 - - * binutils-2.23.2.tar.bz2 - - o binutils-2.23.2\_arv7a.patch - - o binutils-2.23.2\_no-bfd-doc.patch - - * acpica-unix-20130626.tar.gz - -Unpacked and patched ... \textcolor {green}{ok} - -Building GMP 5.1.2 ... \textcolor {green}{ok} - -Building MPFR 3.1.2 ... \textcolor {green}{ok} - -Building MPC 1.0.1 ... \textcolor {green}{ok} - -Building libelf 0.8.13 ... \textcolor {green}{ok} - -Building binutils 2.23.2 ... \textcolor {green}{ok} - -Building GCC 4.7.3 ... ok - -Skipping Expat (Python scripting not enabled) - -Skipping Python (Python scripting not enabled) - -Skipping GDB (GDB support not enabled) - -Building IASL 20130626 ... \textcolor {green}{ok} - -Cleaning up... \textcolor {green}{ok} - -\textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.} -} -If you are lucky, you can get toolchains located in util/crossgcc/xgcc. - -% -% Build Coreboot -% - -\section{Building Coreboot} -\subsection{Build main module of Coreboot} -{ \small -\begin{verbatim} -$ cd coreboot -$ make menuconfig -.config - coreboot v4.0-4895-gc5025a4-dirty Configuration -+------------------------ coreboot Configuration -------------------------+ -| Arrow keys navigate the menu. <Enter> selects submenus --->. | -| Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | -| <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | -| for Search. Legend: [*] built-in [ ] excluded <M> module < > | -| +---------------------------------------------------------------------+ | -| | General setup ---> | | -| | Mainboard ---> | | -| | Architecture (x86) ---> | | -| | Chipset ---> | | -| | Devices ---> | | -| | VGA BIOS ---> | | -| | Display ---> | | -| | PXE ROM ---> | | -| | Generic Drivers ---> | | -| | Console ---> | | -| | [ ] Relocatable Modules | | -| | System tables ---> | | -| | Payload ---> | | -| | Debugging ---> | | -| | --- | | -| +----v(+)-------------------------------------------------------------+ | -+-------------------------------------------------------------------------+ -| <Select> < Exit > < Help > | -+------------------------------------------------------------------------- -\end{verbatim} -} -Select Mainboard -$>$ Mainboard Vendor -$>$ AMD - -$>$ Mainboard Model -$>$ Olive Hill - -Then save, exit and run make. - -{ \small -\begin{verbatim} -$ make -\end{verbatim} -} -The built image, coreboot.rom, is located at folder build. - -\section{Programming coreboot to flash memory} -The image resulting from a coreboot build can be directly programmed to -a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the -Linux flash utility, flashrom. - - -\subsection{Add modules and payload} - -\subsubsection{VGA BIOS} -There is a big Chance that you need to get a VGA BIOS. -{ \small -\begin{verbatim} -.config - coreboot v4.0 Configuration ------------------------------------------------------------------------------- -+-------------------------------- VGA BIOS --------------------------------+ -| Arrow keys navigate the menu. <Enter> selects submenus --->. | -| Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | -| <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | -| for Search. Legend: [*] built-in [ ] excluded <M> module < > module | -| +----------------------------------------------------------------------+ | -| | [*] Add a VGA BIOS image | | -| | (vgabios.bin) VGA BIOS path and filename | | -| | (1002,1306) VGA device PCI IDs | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| +----------------------------------------------------------------------+ | -+--------------------------------------------------------------------------+ -| <Select> < Exit > < Help > | -+--------------------------------------------------------------------------+ -\end{verbatim} -} -Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the -Option ROM from Vendor's website. - -\subsubsection{Payload} -coreboot in itself is "only" minimal code for initializing a mainboard -with peripherals. After the initialization, it jumps to a payload. - -Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS -is setting it in menuconfig. -{ \small -\begin{verbatim} -+------------------------------- Payload ---------------------------------+ -| Arrow keys navigate the menu. <Enter> selects submenus --->. | -| Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | -| <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | -| for Search. Legend: [*] built-in [ ] excluded <M> module < > module | -| +----------------------------------------------------------------------+ | -| | Add a payload (SeaBIOS) ---> | | -| | SeaBIOS version (1.7.2.1) ---> | | -| | [*] Use LZMA compression for payloads (NEW) | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| +----------------------------------------------------------------------+ | -+--------------------------------------------------------------------------+ -| <Select> < Exit > < Help > | -+--------------------------------------------------------------------------+ -\end{verbatim} -The script in Makefile will automatically checkout, config, build the SeaBIOS source, -and integrat the binary into the final image. - -% -% Working with Git -% - -\section{Working with Git} -\subsection{Configuration of Git} -Inside the checkout you should install a commit-msg hook that adds a -Change-Id into commit messages, which uniquely identifies the logical -change in Gerrit even across multiple iterations of the commit. The -hook only needs to be installed once per clone, and installation can -be done with: -{ \small -\begin{verbatim} -$ cd coreboot -$ cp ./util/gitconfig/* .git/hooks -\end{verbatim} -} -configure your name and email in git. -{ \small -\begin{verbatim} -$ git config --global user.name "Your Name Comes Here" -$ git config --global user.email your.email(a)example.com' -\end{verbatim} -} -The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit. -Otherwise you can not push you code to community. - -Then run the following command once, to tell git that by default you -want to submit all commits in the currently checked-out branch for -review on gerrit: -{ \small -\begin{verbatim} -$ git config remote.origin.push HEAD:refs/for/master -\end{verbatim} -} - -The above configurations for git has been integrated into Makefile. You can run -{ \small -\begin{verbatim} -$ make gitconfig -\end{verbatim} -} - -\subsection{Work flow} - -It is recommended that you make a new branch when you start to work, not pushing changes to master. -{ \small -\begin{verbatim} -$ git checkout master -b mybranch -\end{verbatim} -} -After you have done your changes, run: -{ \small -\begin{verbatim} -$ git add file_need_to_submit.c -$ git commit -m "my first change." -\end{verbatim} -} - -% Does anyone have a better word to describe the phylosophy of spliting changes to patches? -You need to realize that the changes you have made should be well devided into -several commits. Each of them has one and only one meaning. You could use git rebase -i to -split, squash, remove, rewrite you comment. - -Here is an example of a well-formatted commit message: - -{ \small -\begin{verbatim} -examplecomponent: Refactor duplicated setup into a function - -Setting up the demo device correctly requires the exact same register -values to be written into each of the PCI device functions. Moving the -writes into a function allows also otherexamplecomponent to use them. - -Signed-off-by: Joe Hacker <joe(a)hacker.email> -\end{verbatim} -} - -Then you can push the code. -{ \small -\begin{verbatim} -$ git push -\end{verbatim} -} - -You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed. - -Often it might happen that the patch you sent for approval is not good -enough from the first attempt. Gerrit and git make it easy to track -patch evolution during the review process until patches meet our -quality standards and are ready for approval. - -You can easily modify a patch sent to gerrit by you or even by someone -else. Just apply it locally using one of the possible ways to do it, -make a new local commit that fixes the issues reported by the -reviewers, then rebase the change by preserving the same Change-ID. We -recommend you to use the git rebase command in interactive mode, - -Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master. - -% -% Working with Gerrit -% - -\section{Working with Gerrit} -\label{sec:gerrit} -If you are a coreboot user, not planning to contribute, you can skip this section. -\subsection{Get gerrit account} -You need to get an OpenID first. Currently Google account give you an OpenID. It means, if you have a gmail account, you have an OpenID. You can try to signed in. -click \url{http://review.coreboot.org} - -%\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png} -{ \small -\begin{verbatim} -+-----------------------------------------------------------+ -|All Projects Documentation Register Sign In | -|Open Merged Abandoned | -|Search for status:open | -+-----------------------------------------------------------+ -|Subject Status Owner Project Branch Updated CR V | -|cpu: Rename.. Alexandru coreboot master 1:20 PM +1 | -|cpu: Only a.. Alexandru coreboot master 1:17 PM X | -|arch/x86: D.. Alexandru coreboot master 1:09 PM | -| | -| Next -> | -|Press '?' to view keyboard shortcuts | Powered by Gerrit | -+-----------------------------------------------------------+ -\end{verbatim} -} -Click ``Sign In'', You will get - -%\includegraphics[width=6.00in,height=4.00in]{openid.png} - -You will be redirected to Google to get logging in. - -% \includegraphics[width=6.00in,height=1.50in]{login.png} -{ \small -\begin{verbatim} -Sign In to Gerrit Code Review at review.coreboot.org -+--------------------------------------------------+ -+--------------------------------------------------+ -[] Remember me -Sign In Cancel -Sign in with a Google Account -Sign in with a Yahoo! ID -What is OpenID? - -OpenID provides secure single-sign-on, without revealing your passwords to this website. - -There are many OpenID providers available. You may already be member of one! - -Get OpenID -\end{verbatim} -} - -\subsection{Configure account} -Click the dropdown button near the user name and click ``Settings'' - -% \includegraphics[width=6.00in,height=4.00in]{settings} -% \epsfig{figure=keystroke_left} -% \epstopdf {file=settings.eps} -% \epsfig{file=settings.eps} - -\label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once. -{ \small -\begin{verbatim} -Profile Username zbao -Preferences Full Name Zheng Bao -Watched Projects Email Address zheng.bao(a)amd.com -Contact Information Registered Jun 28, 2011 4:33 PM -SSH Public Keys Account ID 1000034 -HTTP Password -Identities -Groups -\end{verbatim} -} - -\label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig -{ \small -\begin{verbatim} - Full Name __________________________________ -Preferred Email ______________ Registered Email - -Save Changes -\end{verbatim} -} - -In ``SSH Public Keys'' section, upload your public key. -{ \small -\begin{verbatim} -Status Algorithm Key Comment - -Delete -Add SSH Public Key - > How to Generate an SSH Key -+--------------------------+ -| | -| | -| | -| | -| | -| | -| | -| | -| | -+--------------------------+ -clear Add Close -\end{verbatim} -} - -Click ``Add Key ...'' -Go back to you linux command line and type: -{ \small -\begin{verbatim} -$ ssh-keygen -Generating public/private rsa key pair. -Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa): -Enter passphrase (empty for no passphrase): -Enter same passphrase again: -Your identification has been saved in /home/zhengbao/.ssh/id_rsa. -Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub. -The key fingerprint is: -xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb(a)host.domain -The key's randomart image is: -+--[ RSA 2048]----+ -| | -| | -| | -| | -| | -| | -| | -| | -| | -+-----------------+ -\end{verbatim} -} -The data in ~/.ssh/id\_rsa.pub is your public key. Copy them to the box in the page of ``SSH Public Keys'' and click add. - -In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout. -{ \small -\begin{verbatim} -Username XXX -Password XXXXXXXXXXXX - -Generate Password Clear Password - -\end{verbatim} -} - -\subsection{Reviewing Changes} -For each listed changes in Gerrit, you can review, comment, evaluate, -cherry-pick, and even re-submit them. For you own patches, only you can -abandon them. Click in the file and commit message, you can add in-line comment. - -% -% 14 Glossary -% - -\section{Glossary} -\begin{itemize} -\item payload - -coreboot only cares about low level machine initialization, but also has -very simple mechanisms to boot a file either from FLASHROM or IDE. That -file, possibly a Linux Kernel, a boot loader or Etherboot, are called -payload, since it is the first software executed that does not cope with -pure initialization. - -\item flash device - -Flash devices are commonly used in all different computers since unlike -ROMs they can be electronically erased and reprogrammed. - -\item Gerrit - -Gerrit is a web based code review system, facilitating online code -reviews for projects using the Git version control system. - -Gerrit makes reviews easier by showing changes in a side-by-side -display, and allowing inline comments to be added by any reviewer. - -Gerrit simplifies Git based project maintainership by permitting any -authorized user to submit changes to the master Git repository, rather -than requiring all approved changes to be merged in by hand by the -project maintainer. This functionality enables a more centralized -usage of Git. - -\end{itemize} - -\newpage - -% -% 14 Bibliography -% - -\section{Bibliography} -\subsection{Additional Papers on coreboot} - -\begin{itemize} - \item - \textit{\url{http://www.coreboot.org/Documentation}} -\end{itemize} - -\subsection {Links} - -\begin{itemize} - \item Etherboot: \textit{\url{http://www.etherboot.org/}} - \item OpenBIOS: \textit{\url{http://www.openbios.org/}} - \item Flashrom: \textit{\url{http://www.flashrom.org/}} - \item Seabios: \textit{\url{http://www.seabios.org/}} -\end{itemize} - - -\end{document} diff --git a/Documentation/Doxyfile.coreboot b/Documentation/Doxyfile.coreboot deleted file mode 100644 index e6c06fe..0000000 --- a/Documentation/Doxyfile.coreboot +++ /dev/null @@ -1,1639 +0,0 @@ -# Doxyfile 1.7.1 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all -# text before the first occurrence of this tag. Doxygen uses libiconv (or the -# iconv built into libc) for the transcoding. See -# http://www.gnu.org/software/libiconv for the list of possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = coreboot - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = doxygen - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, -# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English -# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, -# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, -# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = YES - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = YES - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = YES - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 8 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = YES - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified -# scopes will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for -# Fortran. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for -# VHDL. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen to replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the -# methods anyway, you should set this option to NO. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. - -TYPEDEF_HIDES_STRUCT = NO - -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penality. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will rougly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols - -SYMBOL_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default -# anonymous namespace are hidden. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen -# will list include files with double quotes in the documentation -# rather than with sharp brackets. - -FORCE_LOCAL_INCLUDES = NO - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen -# will sort the (brief and detailed) documentation of class members so that -# constructors and destructors are listed first. If set to NO (the default) -# the constructors will appear in the respective orders defined by -# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. -# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO -# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. - -SORT_MEMBERS_CTORS_1ST = NO - -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) -# the group names will appear in their defined order. - -SORT_GROUP_NAMES = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = YES - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the -# Folder Tree View (if specified). The default is YES. - -SHOW_FILES = YES - -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. -# This will remove the Namespaces entry from the Quick Index -# and from the Folder Tree View (if specified). The default is YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command <command> <input-file>, where <command> is the value of -# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. -# You can optionally specify a file name after the option, if omitted -# DoxygenLayout.xml will be used as the name of the layout file. - -LAYOUT_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = YES - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = YES - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = . - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for -# the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = util/romcc/tests \ - util/vgabios \ - util/abuild \ - util/kconfig \ - payloads - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command <filter> <input-file>, where <filter> -# is the value of the INPUT_FILTER tag, and <input-file> is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. -# If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. -# Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. -# The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = NO - -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. -# Otherwise they will link to the documentation. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# If the HTML_FOOTER_DESCRIPTION tag is set to YES, Doxygen will -# add generated date, project name and doxygen version to HTML footer. - -HTML_FOOTER_DESCRIPTION= YES - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. -# Doxygen will adjust the colors in the stylesheet and background images -# according to this color. Hue is specified as an angle on a colorwheel, -# see http://en.wikipedia.org/wiki/Hue for more information. -# For instance the value 0 represents red, 60 is yellow, 120 is green, -# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. -# The allowed range is 0 to 359. - -HTML_COLORSTYLE_HUE = 220 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of -# the colors in the HTML output. For a value of 0 the output will use -# grayscales only. A value of 255 will produce the most vivid colors. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to -# the luminance component of the colors in the HTML output. Values below -# 100 gradually make the output lighter, whereas values above 100 make -# the output darker. The value divided by 100 is the actual gamma applied, -# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, -# and 100 does not change the gamma. - -HTML_COLORSTYLE_GAMMA = 80 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting -# this to NO can help when comparing the output of multiple runs. - -HTML_TIMESTAMP = NO - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = NO - -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find -# it at startup. -# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. - -GENERATE_DOCSET = NO - -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) -# can be grouped. - -DOCSET_FEEDNAME = "Doxygen documentation" - -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen -# will append .docset to the name. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING -# is used to encode HtmlHelp index (hhk), content (hhc) and project file -# content. - -CHM_INDEX_ENCODING = - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated -# that can be used as input for Qt's qhelpgenerator to generate a -# Qt Compressed Help (.qch) of the generated HTML documentation. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can -# be used to specify the file name of the resulting .qch file. -# The path specified is relative to the HTML output folder. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#namespace - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#virtual-folders - -QHP_VIRTUAL_FOLDER = doc - -# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to -# add. For more information please see -# http://doc.trolltech.com/qthelpproject.html#custom-filters - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see -# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> -# Qt Help Project / Custom Filters</a>. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's -# filter section matches. -# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> -# Qt Help Project / Filter Attributes</a>. - -QHP_SECT_FILTER_ATTRS = - -# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can -# be used to specify the location of Qt's qhelpgenerator. -# If non-empty doxygen will try to run qhelpgenerator on the generated -# .qhp file. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files -# will be generated, which together with the HTML files, form an Eclipse help -# plugin. To install this plugin and make it available under the help contents -# menu in Eclipse, the contents of the directory containing the HTML and XML -# files needs to be copied into the plugins directory of eclipse. The name of -# the directory within the plugins directory should be the same as -# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before -# the help appears. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have -# this name. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. -# If the tag value is set to YES, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). -# Windows users are probably better off using the HTML help feature. - -GENERATE_TREEVIEW = YES - -# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, -# and Class Hierarchy pages using a tree view instead of an ordered list. - -USE_INLINE_TREES = YES - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open -# links to external symbols imported via tag files in a separate window. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory -# to force them to be regenerated. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are -# not supported properly for IE 6.0, but are supported on all modern browsers. -# Note that when changing this option you need to delete any form_*.png files -# in the HTML output before the changes have effect. - -FORMULA_TRANSPARENT = YES - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box -# for the HTML output. The underlying search engine uses javascript -# and DHTML and should work on any modern browser. Note that when using -# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets -# (GENERATE_DOCSET) there is already a search function so this one should -# typically be disabled. For large projects the javascript based search engine -# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. - -SEARCHENGINE = YES - -# When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a PHP enabled web server instead of at the web client -# using Javascript. Doxygen will generate the search PHP script and index -# file to put on the web server. The advantage of the server -# based approach is that it scales better to large projects and allows -# full text search. The disadvances is that it is more difficult to setup -# and does not have live searching capabilities. - -SERVER_BASED_SEARCH = NO - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. -# Note that when enabling USE_PDFLATEX this option is only used for -# generating bitmaps for formulas in the HTML output, but not in the -# Makefile that is written to the output directory. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4wide - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -# If LATEX_SOURCE_CODE is set to YES then doxygen will include -# source code with syntax highlighting in the LaTeX output. -# Note that which sources are shown also depends on other settings -# such as SOURCE_BROWSER. - -LATEX_SOURCE_CODE = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. -# This is useful -# if you want to understand what is going on. -# On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see -# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = NO - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is -# allowed to run in parallel. When set to 0 (the default) doxygen will -# base this on the number of processors available in the system. You can set it -# explicitly to a value larger than 0 to get control over the balance -# between CPU load and processing speed. - -DOT_NUM_THREADS = 0 - -# By default doxygen will write a font called FreeSans.ttf to the output -# directory and reference it in all dot files that doxygen generates. This -# font does not include all possible unicode characters however, so when you need -# these (or just want a differently looking font) you can specify the font name -# using DOT_FONTNAME. You need need to make sure dot is able to find the font, -# which can be done by putting it in a standard location or by setting the -# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory -# containing the font. - -DOT_FONTNAME = FreeSans - -# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. -# The default size is 10pt. - -DOT_FONTSIZE = 10 - -# By default doxygen will tell dot to use the output directory to look for the -# FreeSans.ttf font (which doxygen will put there itself). If you specify a -# different font using DOT_FONTNAME you can set the path where dot -# can find it using this tag. - -DOT_FONTPATH = - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = YES - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT options are set to YES then -# doxygen will generate a call dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable call graphs -# for selected functions only using the \callgraph command. - -CALL_GRAPH = YES - -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then -# doxygen will generate a caller dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable caller -# graphs for selected functions only using the \callergraph command. - -CALLER_GRAPH = YES - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the -# number of direct children of the root node in a graph is already larger than -# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not -# seem to support this out of the box. Warning: Depending on the platform used, -# enabling this option may lead to badly anti-aliased labels on the edges of -# a graph (i.e. they become hard to read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = YES - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES diff --git a/Documentation/Doxyfile.coreboot_simple b/Documentation/Doxyfile.coreboot_simple deleted file mode 100644 index 6aed013..0000000 --- a/Documentation/Doxyfile.coreboot_simple +++ /dev/null @@ -1,258 +0,0 @@ -# Doxyfile 1.8.8 -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = coreboot -PROJECT_NUMBER = -PROJECT_BRIEF = "coreboot is an Open Source project aimed at replacing the proprietary BIOS found in most computers." -PROJECT_LOGO = Documentation/coreboot_logo.png -OUTPUT_DIRECTORY = doxygen -CREATE_SUBDIRS = YES -ALLOW_UNICODE_NAMES = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = -ALWAYS_DETAILED_SEC = YES -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES -STRIP_FROM_PATH = -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 8 -ALIASES = -TCL_SUBST = -OPTIMIZE_OUTPUT_FOR_C = YES -OPTIMIZE_OUTPUT_JAVA = NO -OPTIMIZE_FOR_FORTRAN = NO -OPTIMIZE_OUTPUT_VHDL = NO -EXTENSION_MAPPING = -MARKDOWN_SUPPORT = YES -AUTOLINK_SUPPORT = YES -BUILTIN_STL_SUPPORT = NO -CPP_CLI_SUPPORT = NO -SIP_SUPPORT = NO -IDL_PROPERTY_SUPPORT = YES -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO -TYPEDEF_HIDES_STRUCT = NO -LOOKUP_CACHE_SIZE = 0 -EXTRACT_ALL = YES -EXTRACT_PRIVATE = NO -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = YES -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = NO -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = YES -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -SHOW_GROUPED_MEMB_INC = NO -FORCE_LOCAL_INCLUDES = NO -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_MEMBERS_CTORS_1ST = NO -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -STRICT_PROTO_MATCHING = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_FILES = YES -SHOW_NAMESPACES = YES -FILE_VERSION_FILTER = -LAYOUT_FILE = -CITE_BIB_FILES = -QUIET = YES -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = YES -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -INPUT = src -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = -RECURSIVE = YES -EXCLUDE = src/vendorcode -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = -SOURCE_BROWSER = YES -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = NO -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -REFERENCES_LINK_SOURCE = YES -SOURCE_TOOLTIPS = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = -GENERATE_HTML = YES -HTML_OUTPUT = html -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_EXTRA_STYLESHEET = -HTML_EXTRA_FILES = -HTML_COLORSTYLE_HUE = 220 -HTML_COLORSTYLE_SAT = 100 -HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = NO -HTML_INDEX_NUM_ENTRIES = 100 -GENERATE_DOCSET = NO -DOCSET_FEEDNAME = "Doxygen documentation" -DOCSET_BUNDLE_ID = org.doxygen.Project -DOCSET_PUBLISHER_ID = org.doxygen.Publisher -DOCSET_PUBLISHER_NAME = Publisher -GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -CHM_INDEX_ENCODING = -BINARY_TOC = NO -TOC_EXPAND = NO -GENERATE_QHP = NO -QCH_FILE = -QHP_NAMESPACE = org.doxygen.Project -QHP_VIRTUAL_FOLDER = doc -QHP_CUST_FILTER_NAME = -QHP_CUST_FILTER_ATTRS = -QHP_SECT_FILTER_ATTRS = -QHG_LOCATION = -GENERATE_ECLIPSEHELP = NO -ECLIPSE_DOC_ID = org.doxygen.Project -DISABLE_INDEX = NO -GENERATE_TREEVIEW = YES -ENUM_VALUES_PER_LINE = 4 -TREEVIEW_WIDTH = 250 -EXT_LINKS_IN_WINDOW = NO -FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES -USE_MATHJAX = NO -MATHJAX_FORMAT = HTML-CSS -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest -MATHJAX_EXTENSIONS = -MATHJAX_CODEFILE = -SEARCHENGINE = YES -SERVER_BASED_SEARCH = NO -EXTERNAL_SEARCH = NO -SEARCHENGINE_URL = -SEARCHDATA_FILE = searchdata.xml -EXTERNAL_SEARCH_ID = -EXTRA_SEARCH_MAPPINGS = -GENERATE_LATEX = NO -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex -COMPACT_LATEX = NO -PAPER_TYPE = a4wide -EXTRA_PACKAGES = -LATEX_HEADER = -LATEX_FOOTER = -LATEX_EXTRA_FILES = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO -LATEX_BIB_STYLE = plain -GENERATE_RTF = NO -RTF_OUTPUT = rtf -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = -GENERATE_MAN = NO -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_SUBDIR = -MAN_LINKS = NO -GENERATE_XML = NO -XML_OUTPUT = xml -XML_PROGRAMLISTING = YES -GENERATE_DOCBOOK = NO -DOCBOOK_OUTPUT = docbook -DOCBOOK_PROGRAMLISTING = NO -GENERATE_AUTOGEN_DEF = NO -GENERATE_PERLMOD = NO -PERLMOD_LATEX = NO -PERLMOD_PRETTY = YES -PERLMOD_MAKEVAR_PREFIX = -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = -PREDEFINED = __attribute__(x)= -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -EXTERNAL_PAGES = YES -PERL_PATH = /usr/bin/perl -CLASS_DIAGRAMS = YES -MSCGEN_PATH = -DIA_PATH = -HIDE_UNDOC_RELATIONS = NO -HAVE_DOT = NO -DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 -DOT_FONTPATH = -CLASS_GRAPH = YES -COLLABORATION_GRAPH = YES -GROUP_GRAPHS = YES -UML_LOOK = YES -UML_LIMIT_NUM_FIELDS = 10 -TEMPLATE_RELATIONS = NO -INCLUDE_GRAPH = YES -INCLUDED_BY_GRAPH = YES -CALL_GRAPH = YES -CALLER_GRAPH = YES -GRAPHICAL_HIERARCHY = YES -DIRECTORY_GRAPH = YES -DOT_IMAGE_FORMAT = png -INTERACTIVE_SVG = NO -DOT_PATH = -DOTFILE_DIRS = -MSCFILE_DIRS = -DIAFILE_DIRS = -PLANTUML_JAR_PATH = -DOT_GRAPH_MAX_NODES = 50 -MAX_DOT_GRAPH_DEPTH = 0 -DOT_TRANSPARENT = NO -DOT_MULTI_TARGETS = YES -GENERATE_LEGEND = YES -DOT_CLEANUP = YES diff --git a/Documentation/Intel/Board/Galileo_checklist.html b/Documentation/Intel/Board/Galileo_checklist.html deleted file mode 100644 index 3fc04b1..0000000 --- a/Documentation/Intel/Board/Galileo_checklist.html +++ /dev/null @@ -1,162 +0,0 @@ -<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> diff --git a/Documentation/Intel/Board/board.html b/Documentation/Intel/Board/board.html deleted file mode 100644 index 1b2d323..0000000 --- a/Documentation/Intel/Board/board.html +++ /dev/null @@ -1,240 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Board</title> - </head> - <body> - -<h1>x86 Board Development</h1> -<p> - Board development requires System-on-a-Chip (SoC) support. - The combined steps are listed - <a target="_blank" href="../development.html">here</a>. - The development steps for the board are listed below: -</p> -<ol> - <li><a href="#RequiredFiles">Required Files</a></li> - <li>Enable <a href="#SerialOutput">Serial Output</a></li> - <li>Load the <a href="#SpdData">Memory Timing Data</a></li> - <li><a href="#DisablePciDevices">Disable</a> the PCI devices</li> - <li><a href="#AcpiTables">ACPI Tables</a></li> -</ol> - - -<hr> -<h1><a name="RequiredFiles">Required Files</a></h1> -<p> - Create the board directory as src/mainboard/<Vendor>/<Board>. -</p> - -<p> - The following files are required to build a new board: -</p> -<ol> - <li>Kconfig.name - Defines the Kconfig value for the board</li> - <li>Kconfig - <ol type="A"> - <li>Selects the SoC for the board and specifies the SPI flash size - <ol type="I"> - <li>BOARD_ROMSIZE_KB_<Size></li> - <li>SOC_<Vendor>_<Chip Family></li> - </ol> - </li> - <li>Declare the Kconfig values for: - <ol type="I"> - <li>MAINBOARD_DIR</li> - <li>MAINBOARD_PART_NUMBER</li> - <li>MAINBOARD_VENDOR</li> - </ol> - </li> - </ol> - </li> - <li>devicetree.cb - Enable root bridge and serial port - <ol type="A"> - <li>The first line must be "chip soc/Intel/<soc family>"; - this path is used by the generated static.c to include the chip.h - header file - </li> - </ol> - </li> - <li>romstage.c - <ol type="A"> - <li>Add routine mainboard_romstage_entry which calls romstage_common</li> - </ol> - </li> - <li>Configure coreboot build: - <ol type="A"> - <li>Set LOCALVERSION</li> - <li>Select vendor for the board</li> - <li>Select the board</li> - <li>CBFS_SIZE = 0x00100000</li> - <li>Set the CPU_MICROCODE_CBFS_LEN</li> - <li>Set the CPU_MICROCODE_CBFS_LOC</li> - <li>Set the FSP_IMAGE_ID_STRING</li> - <li>Set the FSP_LOC</li> - <li>Disable GOP_SUPPORT</li> - <li>No payload</li> - <li>Choose the default value for all other options</li> - </ol> - </li> -</ol> - - -<hr> -<h1><a name="SerialOutput">Enable Serial Output</a></h1> -<p> - Use the following steps to enable serial output: -</p> -<ol> - <li>Implement the car_mainboard_pre_console_init routine in the com_init.c - file: - <ol type="A"> - <li>Power on and enable the UART controller</li> - <li>Connect the UART receive and transmit data lines to the - appropriate SoC pins - </li> - </ol> - </li> - <li>Add Makefile.inc - <ol type="A"> - <li>Add com_init.c to romstage</li> - </ol> - </li> -</ol> - - -<hr> -<h1><a name="SpdData">Memory Timing Data</a></h1> -<p> - Memory timing data is located in the flash. This data is in the format of - <a target="_blank" href="https://en.wikipedia.org/wiki/Serial_presence_detect">serial presence detect</a> - (SPD) data. - Use the following steps to load the SPD data: -</p> -<ol> - <li>Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the - display of the SPD data being passed to MemoryInit - </li> - <li>Create an "spd" subdirectory</li> - <li>Create an spd/spd.c file for the SPD implementation - <ol type="A"> - <li>Implement the mainboard_fill_spd_data routine - <ol type="i"> - <li>Read the SPD data either from the spd.bin file or using I2C or SMBUS</li> - <li>Fill in the pei_data structure with SPD data for each of the DIMMs</li> - <li>Set the DIMM channel configuration</li> - </ol> - </li> - </ol> - </li> - <li>Add an .spd.hex file containing the memory timing data to the spd subdirectory</li> - <li>Create spd/Makefile.inc - <ol type="A"> - <li>Add spd.c to romstage</li> - <li>Add the .spd.hex file to SPD_SOURCES</li> - </ol> - </li> - <li>Edit Makefile.inc to add the spd subdirectory</li> - <li>Edit romstage.c - <ol type="A"> - <li>Call mainboard_fill_spd_data</li> - <li>Add mainboard_memory_init_params to copy the SPD and DRAM - configuration data from the pei_data structure into the UPDs - for MemoryInit - </li> - </ol> - </li> - <li>Edit devicetree.cb - <ol type="A"> - <li>Include the UPD parameters for MemoryInit except for: - <ul> - <li>Address of SPD data</li> - <li>DRAM configuration set above</li> - </ul> - </li> - </ol> - </li> - <li>A working FSP - <a target="_blank" href="../fsp1_1.html#MemoryInit">MemoryInit</a> - routine is required to complete debugging</li> - <li>Debug the result until port 0x80 outputs - <ol type="A"> - <li>0x34: - - Just after entering - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">raminit</a> - </li> - <li>0x36: - - Just before displaying the - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">UPD parameters</a> - for FSP MemoryInit - </li> - <li>0x92: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_MEMORY_INIT</a> - - Just before calling FSP - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">MemoryInit</a> - </li> - <li>0x37: - - Just after returning from FSP - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">MemoryInit</a> - </li> - </ol> - </li> - <li>Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called</li> -</ol> - - - -<hr> -<h1><a name="DisablePciDevices">Disable PCI Devices</a></h1> -<p> - Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all - of the devices in the system. Edit the devicetree.cb file: -</p> -<ol> - <li>Edit the devicetree.cb file: - <ol type="A"> - <li>Add an entry for a PCI device.function and turn it off. The entry - should look similar to: -<pre><code>device pci 14.0 off end</code></pre> - </li> - <li>Turn on the devices for: - <ul> - <li>Memory Controller</li> - <li>Debug serial device</li> - </ul> - </li> - </ol> - </li> - <li>Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices</li> -</ol> - - - -<hr> -<h1><a name="AcpiTables">ACPI Tables</a></h1> -<ol> - <li>Edit Kconfig - <ol type="A"> - <li>Add "select HAVE_ACPI_TABLES"</li> - </ol> - </li> - <li>Add the acpi_tables.c module: - <ol type="A"> - <li>Include soc/acpi.h</li> - <li>Add the acpi_create_fadt routine - <ol type="I"> - <li>fill in the ACPI header</li> - <li>Call the acpi_fill_in_fadt routine</li> - </ol> - </li> - </ol> - </li> - <li>Add the dsdt.asl module: - </li> -</ol> - - - -<hr> -<p>Modified: 20 February 2016</p> - </body> -</html> diff --git a/Documentation/Intel/Board/galileo.html b/Documentation/Intel/Board/galileo.html deleted file mode 100644 index cdc8fda..0000000 --- a/Documentation/Intel/Board/galileo.html +++ /dev/null @@ -1,114 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Galileo</title> - </head> - <body> - -<h1>Intel® Galileo Development Board</h1> -<table> - <tr> - <td><a target="_blank" href="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg"><img alt="Galileo Gen 2" src="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg" width=500></a></td> - <td> - The Intel® Galileo Gen 2 mainboard code was developed along with the Intel® - <a target="_blank" href="../SoC/quark.html">Quark™</a> SoC: - <ul> - <li><a target="_blank" href="../development.html">Overall</a> development</li> - <li><a target="_blank" href="../SoC/soc.html">SoC</a> support</li> - <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li> - <li><a target="_blank" href="board.html">Board</a> support</li> - <li><a target="_blank" href="Galileo_checklist.html">Implementation Checklist</a></li> - </ul> - </td> - </tr> -</table> - - - -<hr> -<h1>Galileo Board Documentation</h1> -<ul> - <li>Common Components - <ul> - <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li> - <li>Analog Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li> - <li>Ethernet (10/100 MB/S): Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf">DP83848</a></li> - <li>Load Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps22920.pdf">TPS22920x</a></li> - <li>Memory (256 MiB): Micron <a target="_blank" href="https://www.micron.com/~/media/Documents/Products/Data%20Sheet/DRAM/DDR3/1G…">MT41K128M8</a></li> - <li>SoC: Intel® Quark™ <a target="_blank" href="../SoC/quark.html">X-1000</a></li> - <li>Serial EEPROM (1 KiB): ON Semiconductor® <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li> - <li>SPI Flash (8 MiB): Winbond™ <a target="_blank" href="http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.pdf">W25Q64FV</a></li> - <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li> - <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ug/slvu570/slvu570.pdf">TPS652510</a></li> - <li>Termination Regulator: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps51200.pdf">TPS51200</a></li> - </ul> - </li> - <li>Make a bootable <a target="_blank" href="https://software.intel.com/en-us/get-started-galileo-linux-step1">micro SD card</a></li> -</ul> - -<h2>Galileo Gen 2 Board Documentation</h2> -<ul> - <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg">Block Diagram</a></li> - <li><a target="_blank" href="https://software.intel.com/en-us/iot/library/galileo-getting-started">Getting Started</a></li> - <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-ov…">Overview</a></li> - <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg">Port Diagram</a></li> - <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/intelgalileogen2prodbrief_3307…">Product Brief</a></li> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-…">Schematic</a></li> - <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_…">User Guide</a></li> - <li>Components - <ul> - <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li> - <li>I2C 16-channel, 12-bit PWM: NXP Semiconductors <a target="_blank" href="http://cache.nxp.com/documents/data_sheet/PCA9685.pdf">PCA9685</a></li> - <li>I2C I/O Ports: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf">PCAL9535A</a></li> - <li>Octal Buffer/Driver: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf">SN74LV541AT</a></li> - <li>Quadruple Bus Buffer: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf">SN74LV125A</a></li> - <li>Quadruple Bus Buffer with 3-State Outputs: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf">SN74LVC126A</a></li> - <li>Serial EEPROM (1 KiB): ON Semiconductor® <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li> - <li>Single 2-input multiplexer: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf">74LVC1G157</a></li> - <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li> - </ul> - </li> -</ul> - -<h2>Galileo Gen 1 Board Documentation</h2> -<ul> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/gali…">Datasheet</a></li> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-…">Schematic</a></li> - <li>Components - <ul> - <li>A/D: Analog Devices <a target="_blank" href="http://www.analog.com/media/en/technical-documentation/data-sheets/AD7298-1…">AD7298</a></li> - <li>Analog Switch, 2 channel: Texas Instruments <a target="_blank" href="http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li> - <li>EEPROM & GPIO: Cypress <a target="_blank" href="http://www.cypress.com/file/37971/download">CY8C9540A</a></li> - <li>Power Distribution Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps2044b.pdf">TPS2051BDBVR</a></li> - <li>RS232 Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/max3232.pdf">MAX3232</a></li> - <li>Voltage-Level Translator: Texas Instruments<a target="_blank" href="http://www.ti.com/lit/ds/symlink/txs0108e.pdf">TXS0108E</a></li> - </ul> - </li> -</ul> - - - -<hr> -<h1>Debug Tools</h1> -<ul> - <li>Flash Programmer: - <ul> - <li>Dediprog <a target="_blank" href="http://www.dediprog.com/pd/spi-flash-solution/SF100">SF100</a> ISP IC Programmer</li> - </ul> - </li> - <li>JTAG Connector: <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#…">Olimex ARM-JTAG-20-10</a></li> - <li>JTAG Debugger: - <ul> - <li>Olimex LTD <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#…">ARM-USB-OCD-H</a></li> - <li>Tincan Tools <a target="_blank" href="https://www.tincantools.com/wiki/Flyswatter2">Flyswatter2</a></li> - </ul> - </li> - <li><a target="_blank" href="http://download.intel.com/support/processors/quark/sb/sourcedebugusingopeno…">Hardware Setup and Software Installation</a></li> - <li>USB Serial cable: FTDI <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#…">TTL-232R-3V3</a></li> -</ul> - - -<hr> -<p>Modified: 29 February 2016</p> - </body> -</html> diff --git a/Documentation/Intel/SoC/quark.html b/Documentation/Intel/SoC/quark.html deleted file mode 100644 index 9c180da..0000000 --- a/Documentation/Intel/SoC/quark.html +++ /dev/null @@ -1,220 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Quark™ SoC</title> - </head> - <body> - -<h1>Intel® Quark™ SoC</h1> -<table> - <tr> - <td><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-…"><img alt="Quark Block Diagram" src="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-…" width=500></a></td> - <td> - The Quark™ SoC code was developed using the - <a target="_blank" href="../Board/galileo.html">Galileo Gen 2</a> - board: - <ul> - <li><a target="_blank" href="../development.html">Overall</a> development</li> - <li><a target="_blank" href="soc.html">SoC</a> support</li> - <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li> - <li><a target="_blank" href="../Board/board.html">Board</a> support</li> - <li><a target="_blank" href="#QuarkFsp">Quark™ FSP</a></li> - <li><a target="_blank" href="#CorebootPayloadPkg">CorebootPayloadPkg</a></li> - </ul> - </td> - </tr> -</table> - - - -<hr> -<h1>Quark™ Documentation</h1> -<ul> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-…">Block Diagram</a></li> - <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/quark/specificatio…">Specifications</a>: - <ul> - <li><a target="_blank" href="http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-400-MHz">X1000</a> - - <a target="_blank" href="http://www.intel.com/content/www/us/en/search.html?keyword=X1000">Documentation</a>: - <ul> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/quar…">Datasheet</a></li> - <li><a target="_blank" href="http://www.intel.com/content/dam/support/us/en/documents/processors/quark/s…">Developer's Manual</a></li> - <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/…">Product Brief</a></li> - </ul> - </li> - </ul> - </li> - <li><a target="_blank" href="../index.html#Documentation">More documentation</a></li> -</ul> - - - -<hr> -<h1><a name="CorebootPayloadPkg">Quark™ EDK2 CorebootPayloadPkg</a></h1> -<p> -Build Instructions: -</p> -<ol> - <li>Set up <a href="#BuildEnvironment">build environment</a></li> - <li>Linux (assumes GCC48): -<pre><code>build -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc -a IA32 \ - -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 \ - -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL \ - -DMAX_LOGICAL_PROCESSORS=1 -ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd -</code></pre> - </li> - <li>Windows (assumes Visual Studio 2015): -<pre><code>build -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc -a IA32 -t VS2015x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL -DMAX_LOGICAL_PROCESSORS=1 -dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd -</code></pre> - </li> - <li>In the .config for coreboot, set the following Kconfig values: - <ul> - <li>CONFIG_PAYLOAD_ELF=y</li> - <li>CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd"</li> - </ul> - </li> - <li>Build coreboot</li> - <li>Copy the image build/coreboot.rom into flash</li> -</ol> - - - -<hr> -<h1><a name="BuildEnvironment">Quark™ EDK2 Build Environment</a></h1> -<p> - Use the following steps to setup a build environment: -</p> -<ol> - <li>Get the EDK2 sources: - <ol type="A"> - <li>EDK2: git clone <a target="_blank" href="https://github.com/tianocore/edk2.git">https://github.com/tianocore/edk2.git</a></li> - <li>EDK2-non-osi: git clone <a target="_blank" href="https://github.com/tianocore/edk2-non-osi.git">https://github.com/tianocore/edk2-non-osi.git</a></li> - <li>Win32 BaseTools: git clone <a target="_blank" href="https://github.com/tianocore/edk2-BaseTools-win32.git">https://github.com/tianocore/edk2-BaseTools-win32.git</a></li> - </ol> - </li> - <li>Set up a build window: - <ul> - <li>Linux: -<pre><code>export WORKSPACE=$PWD -export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi" -cd edk2 -export WORKSPACE=$PWD -. edksetup.sh -</code></pre> - </li> - <li>Windows: -<pre><code>set WORKSPACE=%CD% -set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi -set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32 -cd edk2 -edksetup.bat -</code></pre> - </li> - </ul> - </li> -</ol> - - - -<hr> -<h1><a name="QuarkFsp">Quark™ FSP</a></h1> -<p> -Getting the Quark FSP source: -</p> -<ol> - <li>Set up an EDK-II <a href="#BuildEnvironment">Build Environment</a></li> - <li>cd edk2</li> - <li>mkdir QuarkFspPkg</li> - <li>cd QuarkFspPkg</li> - <li>Use git to clone <a target="_blank" href="https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp">QuarkFspPkg</a> into the QuarkFpsPkg directory (.)</li> -</ol> - -<h2>Building QuarkFspPkg</h2> -<p> -There are two versions of FSP: FSP 1.1 and FSP 2.0. There are also two -different implementations of FSP, one using subroutines without SEC and -PEI core and the original implementation which relies on SEC and PEI core. -Finally there are two different build x86 types release (r32) and debug (d32). -</p> -<p>Note that the subroutine implementations are a <b>work in progress</b>.</p> -<p> -Build commands shown building debug FSP: -</p> -<ul> - <li>Linux: - <ul> - <li>QuarkFspPkg/BuildFsp1_1.sh -d32</li> - <li>QuarkFspPkg/BuildFsp1_1Pei.sh -d32</li> - <li>QuarkFspPkg/BuildFsp2_0.sh -d32</li> - <li>QuarkFspPkg/BuildFsp2_0Pei.sh -d32</li> - </ul> - <li>Windows: - <ul> - <li>QuarkFspPkg/BuildFsp1_1.bat -d32</li> - <li>Windows: QuarkFspPkg/BuildFsp2_0.bat -d32</li> - </ul> - </li> -</ul> - -<h2>Copying FSP files into coreboot Source Tree</h2> -<p> -There are some helper scripts to copy the FSP output into the coreboot -source tree. The parameters to these scripts are: -</p> -<ol> - <li>EDK2 tree root</li> - <li>coreboot tree root</li> - <li>Build type: DEBUG or RELEASE</li> -</ol> -<p> -Script files: -</p> -<ul> - <li>Linux: - <ul> - <li>QuarkFspPkg/coreboot_fsp1_1.sh</li> - <li>QuarkFspPkg/coreboot_fsp1_1Pei.sh</li> - <li>QuarkFspPkg/coreboot_fsp2_0.sh</li> - <li>QuarkFspPkg/coreboot_fsp2_0Pei.sh</li> - </ul> -</ul> - - -<hr> -<h1>Quark™ EDK2 BIOS</h1> -<p> -Build Instructions: -</p> -<ol> - <li>Set up <a href="#BuildEnvironment">build environment</a></li> - <li>Build the image: - <ul> - <li>Linux: -<pre><code>build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -ls Build/Quark/DEBUG_GCC48/FV/Quark.fd -</code></pre> - </li> - <li>Windows: -<pre><code>build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t VS2012x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd -</code></pre> - </li> - </ul> - </li> -</ol> - -<p> -Documentation: -</p> -<ul> - <li><a target="_blank" href="https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg">EDK II firmware for Intel® Quark™ SoC X1000 based platforms</a></li> - <li>Intel® Quark™ SoC X1000 <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/quark-x1…">UEFI Firmware Writer's Guide</a></li> -</ul> - - - -<hr> -<p>Modified: 17 May 2016</p> - </body> -</html> diff --git a/Documentation/Intel/SoC/soc.html b/Documentation/Intel/SoC/soc.html deleted file mode 100644 index 8f1d75c..0000000 --- a/Documentation/Intel/SoC/soc.html +++ /dev/null @@ -1,734 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>SoC</title> - </head> - <body> - -<h1>x86 System on a Chip (SoC) Development</h1> -<p> - SoC development is best done in parallel with development for a specific - board. The combined steps are listed - <a target="_blank" href="../development.html">here</a>. - The development steps for the SoC are listed below: -</p> -<ol> - <li><a target="_blank" href="../fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li> - <li>SoC <a href="#RequiredFiles">Required Files</a></li> - <li><a href="#Descriptor">Start Booting</a></li> - <li><a href="#EarlyDebug">Early Debug</a></li> - <li><a href="#Bootblock">Bootblock</a></li> - <li><a href="#TempRamInit">TempRamInit</a></li> - <li><a href="#Romstage">Romstage</a> - <ol type="A"> - <li>Enable <a href="#SerialOutput">Serial Output"</a></li> - <li>Get the <a href="#PreviousSleepState">Previous Sleep State</a></li> - <li>Add the <a href="#MemoryInit">MemoryInit</a> Support</li> - <li>Disable the <a href="#DisableShadowRom">Shadow ROM</a></li> - </ol> - </li> - <li><a href="#Ramstage">Ramstage</a> - <ol type="A"> - <li><a href="#DeviceTree">Start Device Tree Processing</a></li> - <li>Set up the <a href="#MemoryMap">Memory Map"</a></li> - </ol> - </li> - <li><a href="#AcpiTables">ACPI Tables</a></li> - <li><a href="#LegacyHardware">Legacy Hardware</a></li> -</ol> - - -<hr> -<h1><a name="RequiredFiles">Required Files</a></h1> -<p> - Create the directory as src/soc/<Vendor>/<Chip Family>. -</p> - -<p> - The following files are required to build a new SoC: -</p> -<ul> - <li>Include files - <ul> - <li>include/soc/pei_data.h</li> - <li>include/soc/pm.h</li> - </ul> - </li> - <li>Kconfig - Defines the Kconfig value for the SoC and selects the tool - chains for the various stages: - <ul> - <li>select ARCH_BOOTBLOCK_<Tool Chain></li> - <li>select ARCH_RAMSTAGE_<Tool Chain></li> - <li>select ARCH_ROMSTAGE_<Tool Chain></li> - <li>select ARCH_VERSTAGE_<Tool Chain></li> - </ul> - </li> - <li>Makefile.inc - Specify the include paths</li> - <li>memmap.c - Top of usable RAM</li> -</ul> - - -<hr> -<h1><a name="Descriptor">Start Booting</a></h1> -<p> - Some SoC parts require additional firmware components in the flash. - This section describes how to add those pieces. -</p> - -<h2>Intel Firmware Descriptor</h2> -<p> - The Intel Firmware Descriptor (IFD) is located at the base of the flash part. - The following command overwrites the base of the flash image with the Intel - Firmware Descriptor: -</p> -<pre><code>dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1</code></pre> - - -<h2><a name="MEB">Management Engine Binary</a></h2> -<p> - Some SoC parts contain and require that the Management Engine (ME) be running - before it is possible to bring the x86 processor out of reset. A binary file - containing the management engine code must be added to the firmware using the - ifdtool. The following commands add this binary blob: -</p> -<pre><code>util/ifdtool/ifdtool -i ME:me.bin build/coreboot.rom -mv build/coreboot.rom.new build/coreboot.rom -</code></pre> - - -<h2><a name="EarlyDebug">Early Debug</a></h2> -<p> - Early debugging between the reset vector and the time the serial port is enabled - is most easily done by writing values to port 0x80. -</p> - - -<h2>Success</h2> -<p> - When the reset vector is successfully invoked, port 0x80 will output the following value: -</p> -<ul> - <li>0x01: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_RESET_VECTOR_CORRECT</a> - - Bootblock successfully executed the - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">reset vector</a> - and entered the 16-bit code at - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">_start</a> - </li> -</ul> - - -<hr> -<h1><a name="Bootblock">Bootblock</a></h1> -<p> - Implement the bootblock using the following steps: -</p> -<ol> - <li>Create the directory as src/soc/<Vendor>/<Chip Family>/bootblock</li> - <li>Add the timestamp.inc file which initializes the floating point registers and saves - the initial timestamp. - </li> - <li>Add the bootblock.c file which: - <ol type="A"> - <li>Enables memory-mapped PCI config access</li> - <li>Updates the microcode by calling intel_update_microcode_from_cbfs</li> - <li>Enable ROM caching</li> - </ol> - </li> - <li>Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file - <ol type="A"> - <li>Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file</li> - <li>Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file</li> - </ol> - </li> - <li>Edit the src/soc/<Vendor>/<Chip Family>/Makefile.inc file - <ol type="A"> - <li>Add the bootblock subdirectory</li> - </ol> - </li> - <li>Edit the src/soc/<Vendor>/<Chip Family>/memmap.c file - <ol type="A"> - <li>Add the fsp/memmap.h include file</li> - <li>Add the mmap_region_granularity routine</li> - </ol> - </li> - <li>Add the necessary .h files to define the necessary values and structures</li> - <li>When successful port 0x80 will output the following values: - <ol type="A"> - <li>0x01: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_RESET_VECTOR_CORRECT</a> - - Bootblock successfully executed the - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">reset vector</a> - and entered the 16-bit code at - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">_start</a> - </li> - <li>0x10: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_ENTER_PROTECTED_MODE</a> - - Bootblock executing in - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit…">32-bit mode</a> - </li> - <li>0x10 - Verstage/romstage reached 32-bit mode</li> - </ol> - </li> -</ol> - -<p> - <b>Build Note:</b> The following files are included into the default bootblock image: -</p> -<ul> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/boot…">src/arch/x86/bootblock_romcc.S</a> - added by <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Make…">src/arch/x86/Makefile.inc</a> - and includes the following files: - <ul> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/prol…">src/arch/x86/prologue.inc</a></li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">src/cpu/x86/16bit/reset16.inc</a></li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit…">src/cpu/x86/16bit/entry16.inc</a></li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit…">src/cpu/x86/32bit/entry32.inc</a></li> - <li>The code in - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/boot…">src/arch/x86/bootblock_romcc.S</a> - includes src/soc/<Vendor>/<Chip Family>/bootblock/timestamp.inc using the - CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above - </li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/sse_e…">src/cpu/x86/sse_enable.inc</a></li> - <li>The code in - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Make…">src/arch/x86/Makefile.inc</a> - invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc: - <ul> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/incl…">src/arch/x86/include/arch/bootblock_romcc.h</a></li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/lapic…">src/cpu/x86/lapic/boot_cpu.c</a></li> - <li>The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in - src/soc/<Vendor>/<Chip Family>/bootblock/bootblock.c - </li> - </ul> - </li> - </ul> - </li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/id.S">src/arch/x86/id.S</a> - added by <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Make…">src/arch/x86/Makefile.inc</a> - </li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit…">src/cpu/intel/fit/fit.S</a> - added by <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit…">src/cpu/intel/fit/Makefile.inc</a> - </li> - <li><a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/walk…">src/arch/x86/walkcbfs.S</a> - added by <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Make…">src/arch/x86/Makefile.inc</a> - </li> -</ul> - - -<hr> -<h1><a name="TempRamInit">TempRamInit</a></h1> -<p> - Enable the call to TempRamInit in two stages: -</p> -<ol> - <li>Finding the FSP binary in the read-only CBFS region</li> - <li>Call TempRamInit</li> -</ol> - - -<h2>Find FSP Binary</h2> -<p> -Use the following steps to locate the FSP binary: -</p> -<ol> - <li>Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file - <ol type="A"> - <li>Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">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="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/intel/com…">util.c</a> - </li> - </ol> - </li> - <li>Debug the result until port 0x80 outputs - <ol type="A"> - <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_TEMP_RAM_INIT</a> - - Just before calling - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">TempRamInit</a> - </li> - <li>Alternating 0xba and 0x01 - The FSP image was not found</li> - </ol> - </li> - <li>Add the <a target="_blank" href="../fsp1_1.html#FspBinary">FSP binary file</a> to the flash image</li> - <li>Set the following Kconfig values: - <ul> - <li>CONFIG_FSP_LOC to the FSP base address specified in the previous step</li> - <li>CONFIG_FSP_IMAGE_ID_STRING</li> - </ul> - </li> - <li>Debug the result until port 0x80 outputs - <ol type="A"> - <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_TEMP_RAM_INIT</a> - - Just before calling - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">TempRamInit</a> - </li> - <li>Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found</li> - </ol> - </li> -</ol> - - -<h2>Calling TempRamInit</h2> -<p> -Use the following steps to debug the call to TempRamInit: -</p> -<ol> - <li>Add the CPU microcode update file - <ol type="A"> - <li>Add the microcode file with the following command -<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b <base address> -f cpu_microcode_blob.bin</code></pre> - </li> - <li>Set the Kconfig values - <ul> - <li>CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step</li> - <li>CONFIG_CPU_MICROCODE_CBFS_LEN</li> - </ul> - </li> - </ol> - </li> - <li>Debug the result until port 0x80 outputs - <ol type="A"> - <li>0x90: <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_TEMP_RAM_INIT</a> - - Just before calling - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">TempRamInit</a> - </li> - <li>0x2A - Just before calling - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">cache_as_ram_main</a> - which is the start of the verstage code which may be part of romstage - </li> - </ol> - </li> -</ol> - - -<hr> -<h1><a name="Romstage">Romstage</a></h1> - -<h2><a name="SerialOutput">Serial Output</a></h2> -<p> - The following steps add the serial output support for romstage: -</p> -<ol> - <li>Create the romstage subdirectory</li> - <li>Add romstage/romstage.c - <ol type="A"> - <li>Program the necessary base addresses</li> - <li>Disable the TCO</li> - </ol> - </li> - <li>Add romstage/Makefile.inc - <ol type="A"> - <li>Add romstage.c to romstage</li> - </ol> - </li> - <li>Add gpio configuration support if necessary</li> - <li>Add the necessary .h files to support the build</li> - <li>Update Makefile.inc - <ol type="A"> - <li>Add the romstage subdirectory</li> - <li>Add the gpio configuration support file to romstage</li> - </ol> - </li> - <li>Set the necessary Kconfig values to enable serial output: - <ul> - <li>CONFIG_DRIVERS_UART_<driver>=y</li> - <li>CONFIG_CONSOLE_SERIAL=y</li> - <li>CONFIG_UART_FOR_CONSOLE=<port></li> - <li>CONFIG_CONSOLE_SERIAL_115200=y</li> - </ul> - </li> -</ol> - - -<h2><a name="PreviousSleepState">Determine Previous Sleep State</a></h2> -<p> - The following steps implement the code to get the previous sleep state: -</p> -<ol> - <li>Implement the fill_power_state routine which determines the previous sleep state</li> - <li>Debug the result until port 0x80 outputs - <ol type="A"> - <li>0x32: - - Just after entering - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">romstage_common</a> - </li> - <li>0x33 - Just after calling - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">soc_pre_ram_init</a> - </li> - <li>0x34: - - Just after entering - <a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">raminit</a> - </li> - </ol> -</ol> - - -<h2><a name="MemoryInit">MemoryInit Support</a></h2> -<p> - The following steps implement the code to support the FSP MemoryInit call: -</p> -<ol> - <li>Add the chip.h header file to define the UPD values which get passed - to MemoryInit. Skip the values containing SPD addresses and DRAM - configuration data which is determined by the board. - <p> - <b>Build Note</b>: The src/mainboard/<Vendor>/<Board>/devicetree.cb - file specifies the default values for these parameters. The build - process creates the static.c module which contains the config data - structure containing these values. - </p> - </li> - <li>Edit romstage/romstage.c - <ol type="A"> - <li>Implement the romstage/romstage.c/soc_memory_init_params routine to - copy the values from the config structure into the UPD structure - </li> - <li>Implement the soc_display_memory_init_params routine to display - the updated UPD parameters by calling fsp_display_upd_value - </li> - </ol> - </li> -</ol> - - -<h2><a name="DisableShadowRom">Disable Shadow ROM</a></h2> -<p> - A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff. - This shadow needs to be disabled to allow RAM to properly respond to - this address range. -</p> -<ol> - <li>Edit romstage/romstage.c and add the soc_after_ram_init routine</li> -</ol> - - -<hr> -<h1><a name="Ramstage">Ramstage</a></h1> - -<h2><a name="DeviceTree">Start Device Tree Processing</a></h2> -<p> - The src/mainboard/<Vendor>/<Board>/devicetree.cb file drives the - execution during ramstage. This file is processed by the util/sconfig utility - to generate build/mainboard/<Vendor>/<Board>/static.c. The various - state routines in - src/lib/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/lib/hardwarem…">hardwaremain.c</a> - call dev_* routines which use the tables in static.c to locate operation tables - associated with the various chips and devices. After location the operation - tables, the state routines call one or more functions depending upon the - state of the state machine. -</p> - -<h3><a name="ChipOperations">Chip Operations</a></h3> -<p> - Kick-starting the ramstage state machine requires creating the operation table - for the chip listed in devicetree.cb: -</p> -<ol> - <li>Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c: - <ol type="A"> - <li> - This chip's operation table has the name - soc_<SoC Vendor>_<SoC Family>_ops which is derived from the - chip path specified in the devicetree.cb file. - </li> - <li>Use the CHIP_NAME macro to specify the name for the chip</li> - <li>For FSP 1.1, specify a .init routine which calls intel_silicon_init</li> - </ol> - </li> - <li>Edit src/soc/<SoC Vendor>/<SoC Family>/Makefile.inc and add chip.c to ramstage</li> -</ol> - -<h3>Domain Operations</h3> -<p> - coreboot uses the domain operation table to initiate operations on all of the - devices in the domain. By default coreboot enables all PCI devices which it - finds. Listing a device in devicetree.cb gives the board vendor control over - the device state. Non-PCI devices may also be listed under PCI device such as - the LPC bus or SMbus devices. -</p> -<ol> - <li>Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c: - <ol type="A"> - <li> - The domain operation table is typically placed in - src/soc/<SoC Vendor>/<SoC Family>/chip.c. - The table typically looks like the following: -<pre><code>static struct device_operations pci_domain_ops = { - .read_resources = pci_domain_read_resources, - .set_resources = pci_domain_set_resources, - .scan_bus = pci_domain_scan_bus, - .ops_pci_bus = pci_bus_default_ops, -}; -</code></pre> - </li> - <li> - Create a .enable_dev entry in the chip operations table which points to a - routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN. -<pre><code> if (dev->path.type == DEVICE_PATH_DOMAIN) { - dev->ops = &pci_domain_ops; - } -</code></pre> - </li> - <li> - During the BS_DEV_ENUMERATE state, ramstage now display the device IDs - for the PCI devices on the bus. - </li> - </ol> - </li> - <li>Set CONFIG_DEBUG_BOOT_STATE=y in the .config file</li> - <li> - Debug the result until the PCI vendor and device IDs are displayed - during the BS_DEV_ENUMERATE state. - </li> -</ol> - - -<h2><a name="DeviceDrivers">PCI Device Drivers</a></h2> -<p> - PCI device drivers consist of a ".c" file which contains a "pci_driver" data - structure at the end of the file with the attribute tag "__pci_driver". This - attribute tag places an entry into a link time table listing the various - coreboot device drivers. -</p> -<p> - Specify the following fields in the table: -</p> -<ol> - <li>.vendor - PCI vendor ID value of the device</li> - <li>.device - PCI device ID value of the device or<br> - .devices - Address of a zero terminated array of PCI device IDs - </li> - <li>.ops - Operations table for the device. This is the address - of a "static struct device_operations" data structure specifying - the routines to execute during the different states and sub-states - of ramstage's processing. - </li> - <li>Turn on the device in mainboard/<Vendor>/<Board>/devicetree.cb</li> - <li> - Debug until the device is on and properly configured in coreboot and - usable by the payload - </li> -</ol> - -<h3><a name="SubsystemIds">Subsystem IDs</a></h3> -<p> - PCI subsystem IDs are assigned during the BS_DEV_ENABLE state. The device - driver may use the common mechanism to assign subsystem IDs by adding - the ".ops_pci" to the pci_driver data structure. This field points to - a "struct pci_operations" that specifies a routine to set the subsystem - IDs for the device. The routine might look something like this: -</p> -<pre><code>static void pci_set_subsystem(device_t dev, unsigned vendor, unsigned device) -{ - if (!vendor || !device) { - vendor = pci_read_config32(dev, PCI_VENDOR_ID); - device = vendor >> 16; - } - printk(BIOS_SPEW, - "PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n", - 0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn), - vendor & 0xffff, device); - pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID, - ((device & 0xffff) << 16) | (vendor & 0xffff)); -} -</code></pre> - - - -<h2>Set up the <a name="MemoryMap">Memory Map</a></h2> -<p> - The memory map is built by the various PCI device drivers during the - BS_DEV_RESOURCES state of ramstage. The northcluster driver will typically - specify the DRAM resources while the other drivers will typically specify - the IO resources. These resources are hung off the device_t data structure by - src/device/device_util.c/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device…">new_resource</a>. -</p> -<p> - During the BS_WRITE_TABLES state, coreboot collects these resources and - places them into a data structure identified by LB_MEM_TABLE. -</p> -<p> - Edit the device driver file: -</p> -<ol> - <li> - Implement a read_resources routine which calls macros defined in - src/include/device/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/devic…">device.h</a> - like: - <ul> - <li>ram_resource</li> - <li>reserved_ram_resource</li> - <li>bad_ram_resource</li> - <li>uma_resource</li> - <li>mmio_resource</li> - </ul> - </li> -</ol> - -<p> - Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state. -</p> - - - -<hr> -<h1><a name="AcpiTables">ACPI Tables</a></h1> -<p> - One of the payloads that needs ACPI tables is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>. -</p> - -<h2>FADT</h2> -<p> - The EDK2 module - CorebootModulePkg/Library/CbParseLib/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbP…">CbParseLib.c</a> - requires that the FADT contains the values in the table below. - These values are placed into a HOB identified by - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CorebootMod…">gUefiAcpiBoardInfoGuid</a> - by routine - CorebootModulePkg/CbSupportPei/CbSupportPei/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CbSupportPe…">CbPeiEntryPoint</a>. -</p> -<table border="1"> - <tr bgcolor="#c0ffc0"> - <td>Coreboot Field</td> - <td>EDK2 Field</td> - <td>gUefiAcpiBoardInfoGuid</td> - <td>Use</li> - <td> - <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf">ACPI Spec.</a> - Section - </td> - </tr> - <tr> - <td>gpe0_blk<br>gpe0_blk_len</td> - <td>Gpe0Blk<br>Gpe0BlkLen</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbP…">PmGpeEnBase</a> - </td> - <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Shutdown</a></td> - <td>4.8.4.1</td> - </tr> - <tr> - <td>pm1a_cnt_blk</td> - <td>Pm1aCntBlk</td> - <td>PmCtrlRegBase</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Shutdown</a><br> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Suspend</a> - </td> - <td>4.8.3.2.1</td> - </tr> - <tr> - <td>pm1a_evt_blk</td> - <td>Pm1aEvtBlk</td> - <td>PmEvtBase</td> - <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Shutdown</a></td> - <td>4.8.3.1.1</td> - </tr> - <tr> - <td>pm_tmr_blk</td> - <td>PmTmrBlk</td> - <td>PmTimerRegBase</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Ac…">Timer</a> - </td> - <td>4.8.3.3</td> - </tr> - <tr> - <td>reset_reg.</td> - <td>ResetReg.Address</td> - <td>ResetRegAddress</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Cold</a> - and - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Warm</a> - resets - </td> - <td>4.3.3.6</td> - </tr> - <tr> - <td>reset_value</td> - <td>ResetValue</td> - <td>ResetValue</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Cold</a> - and - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/Re…">Warm</a> - resets - </td> - <td>4.8.3.6</td> - </tr> -</table> -<p> - The EDK2 data structure is defined in - MdeModulePkg/Include/IndustryStandard/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStanda…">Acpi61.h</a> - The coreboot data structure is defined in - src/arch/x86/include/arch/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/incl…">acpi.h</a> -</p> - -<ol> - <li> - Select <a target="_blank" href="../Board/board.html#AcpiTables">HAVE_ACPI_TABLES</a> - in the board's Kconfig file - </li> - <li>Create a acpi.c module: - <ol type="A"> - <li>Add the acpi_fill_in_fadt routine and initialize the values above</li> - </ol> - </li> -</ol> - - - -<hr> -<h1><a name="LegacyHardware">Legacy Hardware</a></h1> -<p> - One of the payloads that needs legacy hardare is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>. -</p> - -<table border="1"> - <tr bgcolor="c0ffc0"> - <th>Peripheral</th> - <th>Use</th> - <th>8259 Interrupt Vector</th> - <th>IDT Base Offset</th> - <th>Interrupt Handler</th> - </tr> - <tr> - <td> - <a target="_blank" href="http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf">8254</a> - Programmable Interval Timer - </td> - <td> - EDK2: PcAtChipsetPkg/8254TimerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/T…">Timer.c</a> - </td> - <td>0</td> - <td>0x340</td> - <td> - <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/T…">TimerInterruptHandler</a> - </td> - </tr> - <tr> - <td> - <a target="_blank" href="https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uac…">8259</a> - Programmable Interrupt Controller - </td> - <td> - EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8259InterruptC…">8259.c</a> - </td> - <td> - Master interrupts: 0, 2 - 7<br> - Slave interrupts: 8 - 15<br> - Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15 - </td> - <td> - Master: 0x340, 0x350 - 0x378<br> - Slave: 0x380 - 0x3b8<br> - Interrupt descriptors are 8 bytes each - </td> - <td> </td> - </tr> -</table> - -<hr> -<p>Modified: 4 March 2016</p> - </body> -</html> \ No newline at end of file diff --git a/Documentation/Intel/development.html b/Documentation/Intel/development.html deleted file mode 100644 index a2ba278..0000000 --- a/Documentation/Intel/development.html +++ /dev/null @@ -1,377 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Development</title> - </head> - <body> - -<h1>Intel® x86 coreboot/FSP Development Process</h1> -<p> - The x86 development process for coreboot is broken into the following components: -</p> -<ul> - <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li> - <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li> - <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li> -</ul> -<p> - The development process has two main phases: -</p> -<ol> - <li>Minimal coreboot; This phase is single threaded</li> - <li>Adding coreboot features</li> -</ol> - -<h2>Minimal coreboot</h2> -<p> - The combined steps below describe how to bring up a minimal coreboot for a - system-on-a-chip (SoC) and a development board: -</p> -<table> - <tr bgcolor="#ffffc0"> - <td>The initial coreboot steps are single threaded! - The initial minimal FSP development is also single threaded. - Progress can speed up by adding more developers after the minimal coreboot/FSP - implementation reaches the payload. - </td> - </tr> -</table> -<ol> - <li>Get the necessary tools: - <ul> - <li>Linux: Use your package manager to install m4 bison flex and the libcurses development - package. - <ul> - <li>Ubuntu or other Linux distribution that use apt, run: -<pre><code>sudo apt-get install m4 bison flex libncurses5-dev -</code></pre> - </li> - </ul> - </li> - </ul> - </li> - <li>Build the cross tools for i386: - <ul> - <li>Linux: -<pre><code>make crossgcc-i386</code></pre> - To use multiple processors for the toolchain build (which takes a long time), use: -<pre><code>make crossgcc-i386 CPUS=N</code></pre> - where N is the number of cores to use for the build. - </li> - </ul> - </li> - <li>Get something to build: - <ol type="A"> - <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li> - <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li> - <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li> - </ol> - </li> - <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li> - <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li> - <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li> - <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li> - <li>Enable the serial port - <ol type="A"> - <li>Power on, enable and configure GPIOs for the - <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a> - </li> - <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a> - support to romstage - </li> - </ol> - </li> - <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li> - <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li> - <li>Enable DRAM: - <ol type="A"> - <li>Implement the SoC - <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a> - Support - </li> - <li>Implement the board support to read the - <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a> - </li> - </ol> - </li> - <li>Disable the - <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a> - </li> - <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li> - <li> - Implement the .init routine for the - <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> - structure which calls FSP SiliconInit - </li> - <li> - Start ramstage's - <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a> - to display the PCI vendor and device IDs - </li> - <li> - Disable the - <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a> - </li> - <li> - Implement the - <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a> - </li> - <li>coreboot should now attempt to load the payload</li> -</ol> - - - -<h2>Add coreboot Features</h2> -<p> - Most of the coreboot development gets done in this phase. Implementation tasks in this - phase are easily done in parallel. -</p> -<ul> - <li>Payload and OS Features: - <ul> - <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li> - <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li> - </ul> - </li> -</ul> - - - -<hr> -<table border="1"> - <tr bgcolor="#c0ffc0"> - <th colspan=3><h1>Features</h1></th> - </tr> - <tr bgcolor="#c0ffc0"> - <th>SoC</th> - <th>Where</th> - <th>Testing</th> - </tr> - <tr> - <td>8254 Programmable Interval Timer</td> - <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td> - <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td> - </tr> - <tr> - <td>8259 Programmable Interrupt Controller</td> - <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td> - <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td> - </tr> - <tr> - <td>Cache-as-RAM</td> - <td> - <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a> - FSP binary: - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">cache_as_ram.inc</a><br> - Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a> - called from - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">cache_as_ram.inc</a><br> - Disable: FSP 1.1 TempRamExit called from - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a><br> - </td> - <td>FindFSP: POST code 0x90 - (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_TEMP_RAM_INIT</a>) - is displayed<br> - Enable: POST code - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">0x2A</a> - is displayed<br> - Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit - </td> - </tr> - <tr> - <td>Memory Map</td> - <td> - Implement a device driver for the - <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a> - </td> - <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td> - </tr> - <tr> - <td>MTRRs</td> - <td> - Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">setup_stack_and_mtrrs</a><br> - Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a> - </td> - <td>Set: Post code 0x91 - (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/cons…">POST_FSP_TEMP_RAM_EXIT</a>) - is displayed by - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a><br> - Load: Post code 0x3C is displayed by - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a><br> - and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td> - </tr> - <tr> - <td>PCI Device Support</td> - <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td> - <td>The device is detected by coreboot and usable by the payload</td> - </tr> - <tr> - <td>Ramstage state machine</td> - <td> - Implement the chip and domain operations to start the - <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a> - processing - </td> - <td> - During the BS_DEV_ENUMERATE state, ramstage now display the device IDs - for the PCI devices on the bus. - </td> - </tr> - <tr> - <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td> - <td> - Disable: src/soc/<Vendor>/<Chip Family>/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a> - </td> - <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td> - </tr> - - - <tr bgcolor="#c0ffc0"> - <th>Board</th> - <th>Where</th> - <th>Testing</th> - </tr> - <tr> - <td>Device Tree</td> - <td> - <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting - the device tree processing<br> - <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br> - Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a> - <td> - List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br> - Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br> - Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload - </td> - </tr> - <tr> - <td>DRAM</td> - <td> - Load SPD data: src/soc/mainboard/<Vendor>/<Board>/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br> - UPD Setup: - <ul> - <li>src/soc<Vendor>//<Chip Family>/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li> - <li>src/mainboard/<Vendor>/<Board>/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li> - </ul> - FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">raminit.c</a> - </td> - <td>Select the following Kconfig values - <ul> - <li>DISPLAY_HOBS</li> - <li>DISPLAY_UPD_DATA</li> - </ul> - Testing successful if: - <ul> - <li>MemoryInit UPD values are correct</li> - <li>MemoryInit returns 0 (success) and</li> - <li>The the message "ERROR - coreboot's requirements not met by FSP binary!" - is not displayed - </li> - </ul> - </td> - </tr> - <tr> - <td>Serial Port</td> - <td> - SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br> - Enable: src/soc/mainboard/<Board>/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a> - </td> - <td>Debug serial output works</td> - </tr> - - - <tr bgcolor="#c0ffc0"> - <th>Payload</th> - <th>Where</th> - <th>Testing</th> - </tr> - <tr> - <td>ACPI Tables</td> - <td> - SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br> - </td> - <td>Verified by payload or OS</td> - </tr> - - - <tr bgcolor="#c0ffc0"> - <th>FSP</th> - <th>Where</th> - <th>Testing</th> - </tr> - <tr> - <td>TempRamInit</td> - <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td> - <td>FSP binary found: POST code 0x90 - (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/conso…">POST_FSP_TEMP_RAM_INIT</a>) - is displayed<br> - TempRamInit successful: POST code - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">0x2A</a> - is displayed<br> - </td> - </tr> - <tr> - <td>MemoryInit</td> - <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br> - <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br> - </td> - <td>Select the following Kconfig values - <ul> - <li>DISPLAY_HOBS</li> - <li>DISPLAY_UPD_DATA</li> - </ul> - Testing successful if: - <ul> - <li>MemoryInit UPD values are correct</li> - <li>MemoryInit returns 0 (success) and</li> - <li>The the message "ERROR - coreboot's requirements not met by FSP binary!" - is not displayed - </li> - </ul> - </td> - </tr> - <tr> - <td>TempRamExit</td> - <td>src/drivers/intel/fsp1_1/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">after_raminit.S</a></td> - <td>Post code 0x91 - (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/cons…">POST_FSP_TEMP_RAM_EXIT</a>) - is displayed before calling TempRamExit by - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a>, - CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and - Post code 0x39 is displayed by - <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/inte…">after_raminit.S</a><br> - </td> - </tr> - <tr> - <td>SiliconInit</td> - <td> - Implement the .init routine for the - <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure - </td> - <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td> - </tr> - <tr> - <td>FspNotify</td> - <td> - The code which calls FspNotify is located in - src/drivers/intel/fsp1_1/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel…">fsp_util.c</a>. - The fsp_notify_boot_state_callback routine is called three times as specified - by the BOOT_STATE_INIT_ENTRY macros below the routine. - </td> - <td> - The FspNotify routines are called during: - <ul> - <li>BS_DEV_RESOURCES - on exit</li> - <li>BS_PAYLOAD_LOAD - on exit</li> - <li>BS_OS_RESUME - on entry (S3 resume)</li> - </ul> - </td> - </tr> -</table> - - - -<hr> -<p>Modified: 4 March 2016</p> - </body> -</html> \ No newline at end of file diff --git a/Documentation/Intel/fsp1_1.html b/Documentation/Intel/fsp1_1.html deleted file mode 100644 index 1e1e88f..0000000 --- a/Documentation/Intel/fsp1_1.html +++ /dev/null @@ -1,77 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>FSP 1.1</title> - </head> - <body> - -<h1>x86 FSP 1.1 Integration</h1> -<p> - Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC) - and board support. The combined steps are listed - <a target="_blank" href="development.html">here</a>. - The development steps for FSP are listed below: -</p> -<ol> - <li><a href="#RequiredFiles">Required Files</a></li> - <li>Add the <a href="#FspBinary">FSP Binary File</a> to the coreboot File System</li> - <li>Enable <a href="#corebootFspDebugging">coreboot/FSP Debugging</a></li> -</ol> - -<p> - FSP Documentation: -</p> -<ul> - <li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-speci…">V1.1</a></li> -</ul> - -<hr> -<h1><a name="RequiredFiles">Required Files</a></h1> -<h2><a name="corebootRequiredFiles">coreboot Required Files</a></h2> -<ol> - <li>Create the following directories if they do not already exist: - <ul> - <li>src/vendorcode/intel/fsp/fsp1_1/<Chip Family></li> - <li>3rdparty/blobs/mainboard/<Board Vendor>/<Board Name></li> - </ul> - </li> - <li> - The following files may need to be copied from the FSP build or release into the - directories above if they are not present or are out of date: - <ul> - <li>FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/<Chip Family>/FspUpdVpd.h</li> - <li>FSP.bin: 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name>/fsp.bin</li> - </ul> - </li> -</ol> - - -<hr> -<h1><a name="FspBinary">Add the FSP Binary File to coreboot File System</a></h1> -<p> - Add the FSP binary to the coreboot flash image using the following command: -</p> -<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b <base address> -f fsp.bin</code></pre> -<p> - This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the - FSP code for TempRamInit may be executed in place. -</p> - - -<hr> -<h1><a name="corebootFspDebugging">Enable coreboot/FSP Debugging</a></h1> -<p> - Set the following Kconfig values: -</p> -<ul> - <li>CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage</li> - <li>CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit</li> - <li>CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP</li> - <li>CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit</li> -</ul> - - -<hr> -<p>Modified: 17 May 2016</p> - </body> -</html> diff --git a/Documentation/Intel/index.html b/Documentation/Intel/index.html deleted file mode 100644 index 6aaf1be..0000000 --- a/Documentation/Intel/index.html +++ /dev/null @@ -1,128 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Intel® x86</title> - </head> - <body> - -<h1>Intel® x86 Boards</h1> -<ul> - <li><a target="_blank" href="Board/galileo.html">Galileo</a></li> - <li><a target="_blank" href="http://wiki.minnowboard.org/Coreboot">MinnowBoard MAX</a></li> -</ul> - - - -<h1>Intel® x86 SoCs</h1> -<ul> - <li><a target="_blank" href="SoC/quark.html">Quark™</a></li> -</ul> - - - -<hr> -<h1>x86 coreboot Development</h1> -<ul> - <li>Get the <a target="_blank" href="https://www.coreboot.org/Git">coreboot source</li> - <li><a target="_blank" href="development.html">Overall</a> development</li> - <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration - </li> - <li><a target="_blank" href="SoC/soc.html">SoC</a> support</li> - <li><a target="_blank" href="Board/board.html">Board</a> support</li> -</ul> - - - -<hr> -<h1>Payload Development</h1> -<ul> - <li><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> - <ul> - <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Pr…">EDK II Development Process</a></li> - <li>EDK II <a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20White%20pa…">White Papers</a></li> - <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to-Github…">SourceForge to Github Quick Start</a></li> - <li>UEFI <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Errata_…">2.5 Errata A</a></li> - </ul> - </li> -</ul> - - - -<hr> -<h1><a name="Documentation">Documentation</a></h1> -<ul> - <li>Intel® 64 and IA-32 Architectures <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-3…">Software Developer Manual</a></li> - <li><a target="_blank" href="http://www.uefi.org/specifications">UEFI Specifications</a></li> -</ul> - -<h2><a name="Edk2Documentation">EDK-II Documentation</a></h2> -<ul> - <li>Build <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/Build_Spec…">V1.26</a></li> - <li>Coding Standards <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_2_1_Dr…">V2.1</a></li> - <li>DEC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1…">V1.25</a></li> - <li>DSC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC_Spec_1…">V1.26</a></li> - <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Writer's-Guide">Driver Writer's Guide</a></li> - <li>Expression Syntax <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/Expression…">V1.1</a></li> - <li>FDF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF_Spec_1…">V1.26</a></li> - <li>INF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF_Spec_1…">V1.25</a></li> - <li>PCD <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_Infras…">PCD</a>V0.55</li> - <li>UNI <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_File_S…">V1.2 Errata A</a></li> - <li>VRF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_1_9.pdf">V1.9</a></li> -</ul> - -<h2><a name="FspDocumentation">FSP Documentation</a></h2> -<ul> - <li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-speci…">V2.0</a></li> - <li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-speci…">V1.1</a></li> - <li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-speci…">V1.0</a></li> -</ul> - -<h2><a name="FeatureDocumentation">Feature Documentation</a></h2> -<table border="1"> - <tr bgcolor="#c0ffc0"><th>Feature/Specification</th><th>Linux View/Test</th><th>EDK-II View/Test</th></tr> - <tr> - <td><a target="_blank" href="https://en.wikipedia.org/wiki/E820">e820</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/dmesg.1.html">dmesg</a></td> - <td> </td> - </tr> - <tr> - <td><a target="_blank" href="http://www.uefi.org/specifications">ACPI</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/precise/man1/acpidump.1.html">acpidump</a></td> - <td> </td> - </tr> - <tr> - <td><a target="_blank" href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">get-edid | parse-edid</a></td> - <td> </td> - </tr> - <tr> - <td><a target="_blank" href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I2C</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">i2cdetect</a></td> - <td> </td> - </tr> - <tr> - <td><a target="_blank" href="http://www.intel.com/design/archives/processors/pro/docs/242016.htm">Multiprocessor</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/lscpu.1.html">lscpu</a></td> - <td> </td> - </tr> - <tr> - <td><a target="_blank" href="https://pcisig.com/specifications">PCI</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/lspci.8.html">lspci</a></td> - <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">pci</a></td> - </tr> - <tr> - <td><a target="_blank" href="https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.…">SMBIOS</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/dmidecode.8.html">dmidecode</a></td> - <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">smbiosview</a></td> - </tr> - <tr> - <td><a target="_blank" href="http://www.usb.org/developers/docs/">USB</a></td> - <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/xenial/man8/lsusb.8.html">lsusb</a></td> - <td> </td> - </tr> -</table> - -<hr> -<p>Modified: 18 June 2016</p> - </body> -</html> diff --git a/Documentation/Kconfig.tex b/Documentation/Kconfig.tex deleted file mode 100644 index bac8f2b..0000000 --- a/Documentation/Kconfig.tex +++ /dev/null @@ -1,480 +0,0 @@ -\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} diff --git a/Documentation/Makefile b/Documentation/Makefile deleted file mode 100644 index 96b66a9..0000000 --- a/Documentation/Makefile +++ /dev/null @@ -1,70 +0,0 @@ -# -# Makefile for coreboot paper. -# hacked together by Stefan Reinauer <stepan(a)openbios.org> -# - -PDFLATEX=pdflatex -t a4 - -FIGS=codeflow.pdf hypertransport.pdf - -all: CorebootPortingGuide.pdf Kconfig.pdf - -SVG2PDF=$(shell which svg2pdf) -INKSCAPE=$(shell which inkscape) -CONVERT=$(shell which convert) - -codeflow.pdf: codeflow.svg -ifneq ($(strip $(SVG2PDF)),) - svg2pdf $< $@ -else ifneq ($(strip $(INKSCAPE)),) - inkscape $< --export-pdf=$@ -else ifneq ($(strip $(CONVERT)),) - convert $< $@ -endif - -hypertransport.pdf: hypertransport.svg -ifneq ($(strip $(SVG2PDF)),) - svg2pdf $< $@ -else ifneq ($(strip $(INKSCAPE)),) - inkscape $< --export-pdf=$@ -else ifneq ($(strip $(CONVERT)),) - convert $< $@ -endif - -CorebootPortingGuide.toc: $(FIGS) CorebootBuildingGuide.tex - # 2 times to make sure we have a current toc. - $(PDFLATEX) CorebootBuildingGuide.tex - $(PDFLATEX) CorebootBuildingGuide.tex - -CorebootPortingGuide.pdf: $(FIGS) CorebootBuildingGuide.tex CorebootPortingGuide.toc - $(PDFLATEX) CorebootBuildingGuide.tex - -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 >> $@ - -clean: - rm -f *.aux *.idx *.log *.toc *.out $(FIGS) mainboardkconfig.tex skconfig.tex cpukconfig.tex socketfkconfig.tex - -distclean: clean - rm -f CorebootPortingGuide.pdf Kconfig.pdf diff --git a/Documentation/POSTCODES b/Documentation/POSTCODES deleted file mode 100644 index 5d337b6..0000000 --- a/Documentation/POSTCODES +++ /dev/null @@ -1,25 +0,0 @@ -------------------------------------------------------------------------------- -coreboot POST Codes -------------------------------------------------------------------------------- - -This is an (incomplete) list of POST codes emitted by coreboot v4. - -0x10 Entry into protected mode -0x01 Entry into 'crt0.s' reset code jumps to here -0x11 Start copying coreboot to RAM with decompression if compressed -0x12 Copy/decompression finished jumping to RAM -0x80 Entry into coreboot in RAM -0x13 Entry into c_start -0xfe Pre call to hardwaremain() -0x39 Console is initialized -0x40 Console boot message succeeded -0x66 Devices have been enumerated -0x88 Devices have been configured -0x89 Devices have been enabled -0xf8 Entry into elf boot -0xf3 Jumping to payload - -Errors (used in several places): - -0xee Not supposed to get here -0xff Elfload fail or die() called diff --git a/Documentation/README b/Documentation/README new file mode 100644 index 0000000..6884ee0 --- /dev/null +++ b/Documentation/README @@ -0,0 +1,8 @@ +Steps to develop and generate static pages + +0) install hugo via https://github.com/spf13/hugo/releases +1) git clone https://review.coreboot.org/homepage.git +2) cd path/to/homepage/git/util/hugo +3) execute hugo -c path/to/coreboot/src/Documentation server +4) Goto locahost:1313 with your browser. +5) Happy Hacking diff --git a/Documentation/RFC/chip.tex b/Documentation/RFC/chip.tex deleted file mode 100644 index 5e366b8..0000000 --- a/Documentation/RFC/chip.tex +++ /dev/null @@ -1,266 +0,0 @@ - RFC for the chip specification architecture - -\begin{abstract} -At the end of this document is the original message that motivated the -change. -\end{abstract} - -\section{Scope} -This document defines how LinuxBIOS programmers can specify chips that -are used, specified, and initalized. The current scope is for superio -chips, but the architecture should allow for specification of other chips such -as southbridges. Multiple chips of same or different type are supported. - -\section{Goals} -The goals of the new chip architecture are these: -\begin{itemize} -\item seperate implementation details from specification in the Config file -(translation: no more C code in Config files) -\item make the specification easier for people to use and understand -\item remove private details of a given chip to the chip file as much -as possible -\item allow unique register-set-specifiers for each chip -\end{itemize} - -\section{Specification in the Config file} -The specification looks like this: -\begin{verbatim} -chip <name> [path=<path>] ["<configuration>"] -\end{verbatim} -The name is in the standard LinuxBIOS form of type/vendor/name, e.g. -"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the -chip is derived from the first pathname component of the name, and the chip -configuration is derived from the following components. - -The path defines the access mechanism to the chip. -It is optional. If present, it overrides the default path to the chip. - -The configuration defines chip-specific configuration details, and is also -optional. Note that an empty configuration will leave the chip with -no enabled resources. This may be desirable in some cases. - -\section{Results of specifying a chip} - -When one or more chips are specified, the data about the chips -is saved until the entire file is parsed. At this point, the config tool -creates a file in the build directory called chip.c This file contains -a common struct containing information about -each individual chip and an array of pointers to these structures. - -For each chip, there are two structures. The structures contain control -information for the chip, and register initialization information. The -names of the structures are derived by ``flattening'' the chip name, -as in the current linuxbios. For example, superio/ite/xyz uses -two structs, one called superio_ite_xyz_control and one called -superio_ite_xyz_init. The control struct is initialized from the -chip name and path information, and has a pointer to the -config struct. The config struct is initialized from the quote string - -\begin{verbatim} -From rminnich(a)lanl.gov Fri May 16 10:34:13 2003 -Date: Tue, 13 May 2003 08:11:46 -0600 (MDT) -From: ron minnich <rminnich(a)lanl.gov> -To: linuxbios(a)clustermatic.org -Subject: RFC:new superio proposal - -Abstract: - The superio architecture for linuxbios has worked for the last 2 -years but is being stretched to the limit by the changes in superio chips. -The architecture depended on superio resources being relatively constant -between chips, but this assumption no longer holds. In this document we -propose several alternatives and solicit comments. - -Overview: -The superio architecture in linuxbios was developed over time, and -modified as circumstances required. In the beginning it was relatively -simple and assumed only one superio per mainboard. The latest version -allows an arbitrary number of superios per mainboard, and allows complete -specification of the superio base I/O address along with the specification -of reasonable default valures for both the base I/O address and the -superio parameters such as serial enable, baud rate, and so on. - -Specification of superio control parameters is done by a configuration -line such as: - -nsuperio sis/950 com1={1} floppy=1 lpt=1 - -This fragment sets the superio type to sis/950; sets com1, floppy, and lpt -to enabled; and leaves the defaults to com1 (baud rate, etc.) to the -default values. - -While it is not obvious, these configuration parameters are fragments of a -C initializer. The initializers are used to build a statically initialized -structure of this type: - -struct superio { - struct superio_control *super; // the ops for the device. - unsigned int port; // if non-zero, overrides the default port - // com ports. This is not done as an array (yet). - // We think it's easier to set up from python if it is not an - // array. - struct com_ports com1, com2, com3, com4; - // DMA, if it exists. - struct lpt_ports lpt1, lpt2; - /* flags for each device type. Unsigned int. */ - // low order bit ALWAYS means enable. Next bit means to enable - // LPT is in transition, so we leave this here for the moment. - // The winbond chips really stretched the way this works. - // so many functions! - unsigned int ide, floppy, lpt; - unsigned int keyboard, cir, game; - unsigned int gpio1, gpio2, gpio3; - unsigned int acpi,hwmonitor; -}; - -These structures are, in turn, created and statically initialized by a -config-tool-generated structure that defines all the superios. This file -is called nsuperio.c, is created for each mainboard you build, only -appears in the build directory, and looks like this: - -=== -extern struct superio_control superio_winbond_w83627hf_control; - -struct superio superio_winbond_w83627hf= { - &superio_winbond_w83627hf_control, - .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1}; - -struct superio *all_superio[] = {&superio_winbond_w83627hf, -}; - -unsigned long nsuperio = 1; -=== - -This example shows a board with one superio (nsuperio). The superio -consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard, -and hwmonitor enabled. Note that this structure also allows for -over-riding the default superio base, although that capability is rarely -used. - -The control structure is used to define how to access the superio for -purposes of control. It looks like this: -=== -struct superio_control { - void (*pre_pci_init)(struct superio *s); - void (*init)(struct superio *s); - void (*finishup)(struct superio *s); - unsigned int defaultport; /* the defaultport. Can be overridden - * by commands in config - */ - // This is the print name for debugging - char *name; -}; -=== - -There are three methods for stages of hardwaremain. First is pre_pci_init -(for chips like the acer southbridge that require you to enable some -resources BEFORE pci scan); init, called during the 'middle' phase of -hardwaremain; and finishup, called before the payload is loaded. - -This approach was inspired by and borrows heavily on the Plan 9 kernel -configuration tools. - -The problem: - -When the first version of the superio structure came out it was much -smaller. It has grown and in the limit this structure is the union of all -possibly superio chips. Obviously, in the long term, this is not -practical: we can not anticipate all possible superio chips for all time. - -The common PC BIOS solution to this type of problem is to continue with -binary structures but add version numbers to them, so that all code that -uses a given structure has to check the version number. Personally, I find -this grotesque and would rather not work this way. - -Using textual strings for configuration is something I find far more -attractive. Plan 9 has shown that this approach has no real limits and -suffices for configuration tasks. The Linux kernel does more limited use -of strings for configuration, but still depends on them. Strings are -easier to read and work with than binary structures, and more important, a -lot easier to deal with when things start going wrong. - -The proposed solution: - -What follows are three possible ideas for specifying superio resources and -their settings. - -A common part of the new idea is to eliminate the common superio -structure, due to the many variations in chips, and make it invisible -outside a given superio source file -- the superio structure is now -private to a given superio. Thus, sis/950/superio.c would contain its own -superio structure definitions, and also might contain more than once -instance of these structures (consider a board with 2 sis 950 chips). - -The control structure would change as follows: -struct superio_control { - int (*create)(struct superio *s); - void (*pre_pci_init)(struct superio *s); - void (*init)(struct superio *s); - void (*finishup)(struct superio *s); - unsigned int defaultport; /* the defaultport. Can be overridden - * by commands in config - */ - // This is the print name for debugging - char *name; -}; - -I.e. we add a new function for creating the superio. - -Communication of superio settings from linuxbios to the superio would be -via textual strings. The superio structure becomes this: - -struct superio { - struct superio_control *super; // the ops for the device. - unsigned int port; // if non-zero, overrides the default port - struct configuration *config; -}; - - -So now the question becomes, what is the configuration structure? -There are several choices. The simplest, from my point of view, are -keyword-value pairs: -struct configuration { - const char *keyword; - const char *value; -}; - -These get filled in by the config tool as before. The linuxbios libary can -then provide a generic parsing function for the superios to use. - -The remaining question is how should the superio command look in -freebios2? - -superio sis/950 "com1=115200,8n1 lpt=1 com2=9600" - -or - -superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1" - -or - -superio sis/950 ((com1 115200 8n1) (lpt 1)) - -So, my questions: - -1. Does this new scheme look workable. If not, what needs to change? -2. What should the 'struct configuration' be? does keyword/value work? -3. what should the superio command look like? - -Comments welcome. - -I'd like to adopt this "RFC" approach for freebios2 as much as we can. -There was a lot of give-and-take in the early days of linuxbios about -structure and it proved useful. There's a lot that will start happening in -freebios2 now, and we need to try to make sure it will work for everyone. - -Those of you who are doing mainboards, please look at freebios2 and see -how it looks for you. There's a lot of good work that has been done (not -by me so far, thanks Eric and Stefan), and more that needs to be done. -Consider trying out romcc as an "assembly code killer". See how it fits -together and if you can work with it or need changes. Bring comments back -to this list. - -thanks - -ron - -\end{verbatim} diff --git a/Documentation/RFC/config.tex b/Documentation/RFC/config.tex deleted file mode 100644 index 97fec9d..0000000 --- a/Documentation/RFC/config.tex +++ /dev/null @@ -1,290 +0,0 @@ - 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. diff --git a/Documentation/abi-data-consumption.txt b/Documentation/abi-data-consumption.txt deleted file mode 100644 index 81442e7..0000000 --- a/Documentation/abi-data-consumption.txt +++ /dev/null @@ -1,22 +0,0 @@ -This text describes the ABI coreboot presents to downstream users. Such -users are payloads and/or operating systems. Therefore, this text serves -at what can be relied on for downstream consumption. Anything not explicitly -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/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. - -In 2009 cbmem was added to coreboot. The "CBMEM high table memory manager" -serves a way for coreboot to bookkeep its own internal data. While some -of this data may be exposed through the coreboot tables the data structures -used to manage the data within the cbmem area is subject to change. - -Provided the above, if one needs a piece of data exposed to the OS -or payload it should reside within the coreboot tables. If it isn't there -then a code change will be required to add it to the coreboot tables. diff --git a/Documentation/beginverbatim.tex b/Documentation/beginverbatim.tex deleted file mode 100644 index 453714c..0000000 --- a/Documentation/beginverbatim.tex +++ /dev/null @@ -1 +0,0 @@ -\begin{verbatim} diff --git a/Documentation/build_system.md b/Documentation/build_system.md deleted file mode 100644 index 787c833..0000000 --- a/Documentation/build_system.md +++ /dev/null @@ -1,86 +0,0 @@ -# The coreboot build system -(this document is still incomplete and will be filled in over time) - -## General operation -The coreboot build system is based on GNU make but extends it significantly -to the point of providing its own custom language. -The overhead of learning this new syntax is (hopefully) offset by its lower -complexity. - -The build system is defined in the toplevel `Makefile` and `toolchain.inc` -and is supposed to be generic (and is in fact used with a number of other -projects). Project specific configuration should reside in files called -`Makefile.inc`. - -In general, the build system provides a number of "classes" that describe -various parts of the build. These cover the various build targets in coreboot -such as the stages, subdirectories with more source code, and the general -addition of files. - -Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used -by filling in a variable of that name followed by `-y` (eg. `romstage-y`, -`subdirs-y`, `cbfs-files-y`). -The `-y` suffix allows a simple interaction with our Kconfig build -configuration system: Kconfig options are available as variables starting -with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty. - -This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to -`class` depending on the choice for `FOO`. - -## classes -Classes can be defined as required. `subdirs` is handled internally since -it's parsed per subdirectory to add further directories to the rule set. - -TODO: explain how to create new classes and how to evaluate them. - -### subdirs -`subdirs` contains subdirectories (relative to the current directory) that -should also be handled by the build system. The build system expects these -directories to contain a file called `Makefile.inc`. - -Subdirectories are not read at the point where the `subdirs` statement -resides but later, after the current directory is handled (and potentially -others, too). - -### cbfs-files -This class is used to add files to the final CBFS image. Since several more -options need to be maintained than can comfortably fit in that single -variable, additional variables are used. - -`cbfs-files-y` contains the file name used in the CBFS image (called `foo` -here). Additional options are added in `foo-$(option)` variables. The -supported options are: - -* `file`: The on-disk file to add as `foo` (required) -* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary` - (required) -* `compression`: Can be `none` or `lzma` (default: none) -* `position`: An absolute position constraint for the placement of the file - (default: none) -* `align`: Minimum alignment for the file (default: none) -* `options`: Additional cbfstool options (default: none) - -`position` and `align` are mutually exclusive. - -#### FMAP region support -With the addition of FMAP flash partitioning support to coreboot, there was a -need to extend the specification of files to provide more precise control -which regions should contain which files, and even change some flags based on -the region. - -Since FMAP policies depend on features using FMAP, that's kept separate from -the cbfs-files class. - -The `position` and `align` options for file `foo` can be overwritten for a -region `REGION` using `foo-REGION-position` and `foo-REGION-align`. - -The regions that each file should end in can be defined by overriding a -function called `regions-for-file` that's called as -`$(call regions-for-file,$(filename))` and should return a comma-separated -list of regions, such as `REGION1,REGION2,REGION3`. - -The default implementation just returns `COREBOOT` (the default region) for -all files. - -vboot provides its own implementation of `regions-for-file` that can be used -as reference in `src/vboot/Makefile.inc`. diff --git a/Documentation/cbfs.txt b/Documentation/cbfs.txt deleted file mode 100644 index 7ecc901..0000000 --- a/Documentation/cbfs.txt +++ /dev/null @@ -1,421 +0,0 @@ - -Received: from www.crouse-house.com ([199.45.160.146] - for coreboot(a)coreboot.org; Fri, 19 Dec 2008 23:11:59 +0100 -From: Jordan Crouse <jordan(a)cosmicpenguin.net> - - -Greetings. I apologize for the incompleteness of what I am about to -discuss. I was planning on working on it leisurely, but my employment -circumstances changed and I've been trying to get it completed in a -hurry before I had to leave it behind. - -I've been thinking a lot about LAR lately, and ways to make it more -extensible and robust. Marc and I have been trading ideas back and -forth for a number of months, and over time a clear idea of what I -wanted to do started to take shape. - -My goal was to add small things to LAR while retaining the overall -scheme. Over time, the scheme evolved slightly, but I think you'll find -that it remains true to the original idea. Below is the beginnings of -an architecture document - I did it in text form, but if met with -aclaim, it should be wikified. This presents what I call CBFS - the -next generation LAR for next generation Coreboot. Its easier to -describe what it is by describing what changed: - -A header has been added somewhere in the bootblock similar to Carl -Daniel's scheme. In addition to the coreboot information, the header -reports the size of the ROM, the alignment of the blocks, and the offset -of the first component in the CBFS. The master header provides all -the information LAR needs plus the magic number information flashrom needs. - -Each "file" (or component, as I style them) now has a type associated -with it. The type is used by coreboot to identify the type of file that -it is loading, and it can also be used by payloads to group items in the -CBFS by type (i.e - bayou can ask for all components that are payloads). - -The header on each "file" (or component, as I like to style them) has -been simplified - We now only store the length, the type, the checksum, -and the offset to the data. The name scheme remains the same. The -addtional information, which is component specific, has been moved to -the component itself (see below). - -The components are arranged in the ROM aligned along the specified -alignment from the master header - this is to facilitate partial re-write. - -Other then that, the LAR ideas remain pretty much the same. - -The plan for moving the metadata to the components is to allow many -different kinds of components, not all of which are groked by coreboot. - However, there are three essential component types that are groked by -coreboot, and they are defined: - -stage - the stage is being parsed from the original ELF, and stored in -the ROM as a single blob of binary data. The load address, start -address, compression type and length are stored in the component sub-header. - -payload - this is essentially SELF in different clothing - same idea as -SELF, with the sub-header as above. - -optionrom - This is in flux - right now, the optionrom is stored -unadulterated and uncompressed, but that is likely to be changed. - -Following this email are two replies containing the v3 code and a new -ROM tool to implement this respectively. I told you that I was trying -to get this out before I disappear, and I'm not kidding - the code is -compile tested and not run-tested. I hope that somebody will embrace -this code and take it the rest of the way, otherwise it will die a -pretty short death. - -I realize that this will start an awesome flamewar, and I'm looking -forward to it. Thanks for listening to me over the years - and good -luck with coreboot. When you all make a million dollars, send me a few -bucks, will you? - -Jordan - -Coreboot CBFS Specification -Jordan Crouse <jordan(a)cosmicpenguin.net> - -= Introduction = - -This document describes the coreboot CBFS specification (from here -referred to as CBFS). CBFS is a scheme for managing independent chunks -of data in a system ROM. Though not a true filesystem, the style and -concepts are similar. - - -= Architecture = - -The CBFS architecture looks like the following: - -/---------------\ <-- Start of ROM -| /-----------\ | --| -| | Header | | | -| |-----------| | | -| | Name | | |-- Component -| |-----------| | | -| |Data | | | -| |.. | | | -| \-----------/ | --| -| | -| /-----------\ | -| | Header | | -| |-----------| | -| | Name | | -| |-----------| | -| |Data | | -| |.. | | -| \-----------/ | -| | -| ... | -| /-----------\ | -| | | | -| | Bootblock | | -| | --------- | | -| | Reset | | <- 0xFFFFFFF0 -| \-----------/ | -\---------------/ - - -The CBFS architecture consists of a binary associated with a physical -ROM disk referred hereafter as the ROM. A number of independent of -components, each with a header prepended on to data are located within -the ROM. The components are nominally arranged sequentially, though they -are aligned along a pre-defined boundary. - -The bootblock occupies the last 20k of the ROM. Within -the bootblock is a master header containing information about the ROM -including the size, alignment of the components, and the offset of the -start of the first CBFS component within the ROM. - -= Master Header = - -The master header contains essential information about the ROM that is -used by both the CBFS implementation within coreboot at runtime as well -as host based utilities to create and manage the ROM. The master header -will be located somewhere within the bootblock (last 20k of the ROM). A -pointer to the location of the header will be located at offset --4 from the end of the ROM. This translates to address 0xFFFFFFFC on a -normal x86 system. The pointer will be to physical memory somewhere -between - 0xFFFFB000 and 0xFFFFFFF0. This makes it easier for coreboot -to locate the header at run time. Build time utilities will -need to read the pointer and do the appropriate math to locate the header. - -The following is the structure of the master header: - -struct cbfs_header { - u32 magic; - u32 version; - u32 romsize; - u32 bootblocksize; - u32 align; - u32 offset; - u32 architecture; - u32 pad[1]; -} __attribute__((packed)); - -The meaning of each member is as follows: - -'magic' is a 32 bit number that identifies the ROM as a CBFS type. The -magic -number is 0x4F524243, which is 'ORBC' in ASCII. - -'version' is a version number for CBFS header. cbfs_header structure may be -different if version is not matched. - -'romsize' is the size of the ROM in bytes. Coreboot will subtract 'size' from -0xFFFFFFFF to locate the beginning of the ROM in memory. - -'bootblocksize' is the size of bootblock reserved in firmware image. - -'align' is the number of bytes that each component is aligned to within the -ROM. This is used to make sure that each component is aligned correctly -with -regards to the erase block sizes on the ROM - allowing one to replace a -component at runtime without disturbing the others. - -'offset' is the offset of the the first CBFS component (from the start of -the ROM). This is to allow for arbitrary space to be left at the beginning -of the ROM for things like embedded controller firmware. - -'architecture' describes which architecture (x86, arm, ...) this CBFS is created -for. - -= Bootblock = -The bootblock is a mandatory component in the ROM. It is located in the -last -20k of the ROM space, and contains, among other things, the location of the -master header and the entry point for the loader firmware. The bootblock -does not have a component header attached to it. - -= Components = - -CBFS components are placed in the ROM starting at 'offset' specified in -the master header and ending at the bootblock. Thus the total size -available -for components in the ROM is (ROM size - 20k - 'offset'). Each CBFS -component is to be aligned according to the 'align' value in the header. -Thus, if a component of size 1052 is located at offset 0 with an 'align' -value -of 1024, the next component will be located at offset 2048. - -Each CBFS component will be indexed with a unique ASCII string name of -unlimited size. - -Each CBFS component starts with a header: - -struct cbfs_file { - char magic[8]; - unsigned int len; - unsigned int type; - unsigned int checksum; - unsigned int offset; -}; - -'magic' is a magic value used to identify the header. During runtime, -coreboot will scan the ROM looking for this value. The default magic is -the string 'LARCHIVE'. - -'len' is the length of the data, not including the size of the header and -the size of the name. - -'type' is a 32 bit number indicating the type of data that is attached. -The data type is used in a number of ways, as detailed in the section -below. - -'checksum' is a 32bit checksum of the entire component, including the -header and name. - -'offset' is the start of the component data, based off the start of the -header. -The difference between the size of the header and offset is the size of the -component name. - -Immediately following the header will be the name of the component, -which will -null terminated and 16 byte aligned. The following picture shows the -structure of the header: - -/--------\ <- start -| Header | -|--------| <- sizeof(struct cbfs_file) -| Name | -|--------| <- 'offset' -| Data | -| ... | -\--------/ <- start + 'offset' + 'len' - -== Searching Alogrithm == - -To locate a specific component in the ROM, one starts at the 'offset' -specified in the CBFS master header. For this example, the offset will -be 0. - - From that offset, the code should search for the magic string on the -component, jumping 'align' bytes each time. So, assuming that 'align' is -16, the code will search for the string 'LARCHIVE' at offset 0, 16, 32, etc. -If the offset ever exceeds the allowable range for CBFS components, then no -component was found. - -Upon recognizing a component, the software then has to search for the -specific name of the component. This is accomplished by comparing the -desired name with the string on the component located at -offset + sizeof(struct cbfs_file). If the string matches, then the -component -has been located, otherwise the software should add 'offset' + 'len' to -the offset and resume the search for the magic value. - -== Data Types == - -The 'type' member of struct cbfs_file is used to identify the content -of the component data, and is used by coreboot and other -run-time entities to make decisions about how to handle the data. - -There are three component types that are essential to coreboot, and so -are defined here. - -=== Stages === - -Stages are code loaded by coreboot during the boot process. They are -essential to a successful boot. Stages are comprised of a single blob -of binary data that is to be loaded into a particular location in memory -and executed. The uncompressed header contains information about how -large the data is, and where it should be placed, and what additional memory -needs to be cleared. - -Stages are assigned a component value of 0x10. When coreboot sees this -component type, it knows that it should pass the data to a sub-function -that will process the stage. - -The following is the format of a stage component: - -/--------\ -| Header | -|--------| -| Binary | -| .. | -\--------/ - -The header is defined as: - -struct cbfs_stage { - unsigned int compression; - unsigned long long entry; - unsigned long long load; - unsigned int len; - unsigned int memlen; -}; - -'compression' is an integer defining how the data is compressed. There -are three compression types defined by this version of the standard: -none (0x0), lzma (0x1), and nrv2b (0x02, deprecated), though additional -types may be added assuming that coreboot understands how to handle the scheme. - -'entry' is a 64 bit value indicating the location where the program -counter should jump following the loading of the stage. This should be -an absolute physical memory address. - -'load' is a 64 bit value indicating where the subsequent data should be -loaded. This should be an absolute physical memory address. - -'len' is the length of the compressed data in the component. - -'memlen' is the amount of memory that will be used by the component when -it is loaded. - -The component data will start immediately following the header. - -When coreboot loads a stage, it will first zero the memory from 'load' to -'memlen'. It will then decompress the component data according to the -specified scheme and place it in memory starting at 'load'. Following that, -it will jump execution to the address specified by 'entry'. -Some components are designed to execute directly from the ROM - coreboot -knows which components must do that and will act accordingly. - -=== Payloads === - -Payloads are loaded by coreboot following the boot process. - -Stages are assigned a component value of 0x20. When coreboot sees this -component type, it knows that it should pass the data to a sub-function -that will process the payload. Furthermore, other run time -applications such as 'bayou' may easily index all available payloads -on the system by searching for the payload type. - - -The following is the format of a stage component: - -/-----------\ -| Header | -| Segment 1 | -| Segment 2 | -| ... | -|-----------| -| Binary | -| .. | -\-----------/ - -The header is as follows: - -struct cbfs_payload { - struct cbfs_payload_segment segments; -} - -The header contains a number of segments corresponding to the segments -that need to be loaded for the payload. - -The following is the structure of each segment header: - -struct cbfs_payload_segment { - unsigned int type; - unsigned int compression; - unsigned int offset; - unsigned long long load_addr; - unsigned int len; - unsigned int mem_len; -}; - -'type' is the type of segment, one of the following: - -PAYLOAD_SEGMENT_CODE 0x45444F43 The segment contains executable code -PAYLOAD_SEGMENT_DATA 0x41544144 The segment contains data -PAYLOAD_SEGMENT_BSS 0x20535342 The memory speicfied by the segment - should be zeroed -PAYLOAD_SEGMENT_PARAMS 0x41524150 The segment contains information for - the payload -PAYLOAD_SEGMENT_ENTRY 0x52544E45 The segment contains the entry point - for the payload - -'compression' is the compression scheme for the segment. Each segment can -be independently compressed. There are three compression types defined by -this version of the standard: none (0x0), lzma (0x1), and nrv2b -(0x02, deprecated), though additional types may be added assuming that -coreboot understands how to handle the scheme. - -'offset' is the address of the data within the component, starting from -the component header. - -'load_addr' is a 64 bit value indicating where the segment should be placed -in memory. - -'len' is a 32 bit value indicating the size of the segment within the -component. - -'mem_len' is the size of the data when it is placed into memory. - -The data will located immediately following the last segment. - -=== Option ROMS === - -The third specified component type will be Option ROMs. Option ROMS will -have component type '0x30'. They will have no additional header, the -uncompressed binary data will be located in the data portion of the -component. - -=== NULL === - -There is a 4th component type ,defined as NULL (0xFFFFFFFF). This is -the "don't care" component type. This can be used when the component -type is not necessary (such as when the name of the component is unique. -i.e. option_table). It is recommended that all components be assigned a -unique type, but NULL can be used when the type does not matter. diff --git a/Documentation/codeflow.svg b/Documentation/codeflow.svg deleted file mode 100644 index bed9599..0000000 --- a/Documentation/codeflow.svg +++ /dev/null @@ -1,234 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" - width="256px" height="640px" viewBox="0 0 256 640" enable-background="new 0 0 256 640" xml:space="preserve"> -<font horiz-adv-x="1000"> -<font-face font-family="MyriadPro-Regular" units-per-em="1000" underline-position="-100" underline-thickness="50"/> -<missing-glyph horiz-adv-x="500" d="M0,0l500,0l0,700l-500,0M250,395l-170,255l340,0M280,350l170,255l0,-510M80,50l170,255l170,-255M50,605l170,-255l-170,-255z"/> -<glyph unicode="A" horiz-adv-x="612" d="M424,212l72,-212l93,0l-230,674l-104,0l-230,-674l90,0l70,212M203,280l66,195C283,516 293,558 303,597l2,0C315,558 325,518 340,474l67,-194z"/> -<glyph unicode="B" horiz-adv-x="542" d="M76,2C105,-2 151,-6 211,-6C321,-6 397,14 443,57C478,89 501,134 501,192C501,292 426,345 362,360l0,3C432,388 476,445 476,511C476,564 454,604 419,630C378,664 322,679 235,679C175,679 114,673 76,664M163,606C177,609 200,612 240,612C328,612 387,580 387,502C387,437 333,388 242,388l-79,0M163,323l72,0C330,323 409,284 409,193C409,95 326,62 236,62C205,62 181,63 163,66z"/> -<glyph unicode="C" horiz-adv-x="580" d="M529,91C494,74 440,63 386,63C223,63 128,168 128,334C128,511 233,612 391,612C447,612 494,600 526,584l22,71C525,667 471,685 388,685C179,685 36,543 36,331C36,109 178,-11 368,-11C450,-11 515,5 546,21z"/> -<glyph unicode="D" horiz-adv-x="666" d="M76,2C120,-3 171,-6 234,-6C365,-6 469,28 533,91C595,153 630,243 630,353C630,462 595,540 534,595C475,649 386,679 261,679C192,679 129,673 76,664M163,601C186,606 220,610 265,610C449,610 539,509 538,350C538,168 438,64 251,64C217,64 185,65 163,68z"/> -<glyph unicode="E" horiz-adv-x="492" d="M424,388l-261,0l0,213l277,0l0,73l-365,0l0,-674l380,0l0,73l-292,0l0,243l261,0z"/> -<glyph unicode="F" horiz-adv-x="487" d="M75,0l88,0l0,305l254,0l0,72l-254,0l0,224l275,0l0,73l-363,0z"/> -<glyph unicode="H" horiz-adv-x="652" d="M75,674l0,-674l88,0l0,316l326,0l0,-316l88,0l0,674l-88,0l0,-282l-326,0l0,282z"/> -<glyph unicode="I" horiz-adv-x="239" d="M75,674l0,-674l88,0l0,674z"/> -<glyph unicode="L" horiz-adv-x="472" d="M75,0l376,0l0,73l-288,0l0,601l-88,0z"/> -<glyph unicode="M" horiz-adv-x="804" d="M660,0l86,0l-42,674l-111,0l-120,-326C443,263 419,189 401,121l-2,0C381,191 359,265 331,348l-115,326l-111,0l-47,-674l83,0l18,289C165,391 170,503 172,587l2,0C193,507 219,421 251,325l110,-321l66,0l119,327C580,424 607,509 631,587l2,0C633,504 639,390 644,296z"/> -<glyph unicode="N" horiz-adv-x="658" d="M158,0l0,288C158,400 157,481 152,566l3,1C188,494 233,417 280,342l214,-342l88,0l0,674l-82,0l0,-282C500,287 502,205 510,115l-3,-1C476,183 436,254 387,333l-215,341l-96,0l0,-674z"/> -<glyph unicode="O" horiz-adv-x="689" d="M348,686C168,686 36,546 36,332C36,128 160,-11 339,-11C511,-11 652,113 652,344C652,545 533,686 348,686M345,615C490,615 560,475 560,340C560,187 482,60 344,60C206,60 128,189 128,334C128,481 200,615 345,615z"/> -<glyph unicode="P" horiz-adv-x="532" d="M76,0l87,0l0,270C183,265 207,264 233,264C318,264 392,289 439,338C473,373 491,421 491,482C491,542 468,591 432,623C392,659 329,679 243,679C173,679 118,673 76,666M163,603C178,607 207,610 245,610C340,610 404,567 404,477C404,386 340,334 235,334C206,334 182,336 163,341z"/> -<glyph unicode="Q" horiz-adv-x="689" d="M657,-26C600,-16 527,0 460,17l0,4C572,61 652,171 652,345C652,544 533,686 349,686C167,686 36,547 36,331C36,113 172,-5 333,-11C346,-11 359,-16 374,-21C452,-48 541,-75 632,-99M344,60C206,60 128,189 128,333C128,479 200,615 347,615C490,615 560,476 560,340C560,187 482,60 344,60z"/> -<glyph unicode="R" horiz-adv-x="538" d="M76,0l87,0l0,292l82,0C324,289 361,254 381,161C399,77 414,20 425,0l90,0C501,26 485,91 463,185C447,255 416,303 365,321l0,3C435,348 491,407 491,495C491,548 471,594 438,624C397,661 336,679 243,679C184,679 120,673 76,665M163,604C178,608 207,611 249,611C341,611 404,573 404,486C404,409 345,358 252,358l-89,0z"/> -<glyph unicode="S" horiz-adv-x="493" d="M42,33C78,9 149,-11 214,-11C373,-11 449,80 449,184C449,283 392,338 278,382C185,418 144,449 144,512C144,558 179,613 271,613C332,613 377,594 398,581l24,71C393,669 342,685 274,685C143,685 56,607 56,502C56,408 124,350 234,310C325,276 361,239 361,177C361,109 309,62 220,62C160,62 104,81 65,106z"/> -<glyph unicode="T" horiz-adv-x="497" d="M204,0l88,0l0,600l206,0l0,74l-499,0l0,-74l205,0z"/> -<glyph unicode="U" horiz-adv-x="647" d="M75,674l0,-397C75,67 179,-11 317,-11C463,-11 572,73 572,280l0,394l-88,0l0,-400C484,126 419,60 320,60C230,60 163,124 163,274l0,400z"/> -<glyph unicode="a" horiz-adv-x="482" d="M413,297C413,393 377,494 229,494C168,494 109,477 69,452l20,-59C123,416 170,429 216,429C315,430 326,357 326,318l0,-10C139,309 35,245 35,128C35,58 85,-11 183,-11C252,-11 304,23 331,61l3,0l7,-61l79,0C415,33 413,74 413,116M328,163C328,155 327,145 324,135C310,94 269,54 205,54C161,54 123,80 123,138C123,232 232,249 328,247z"/> -<glyph unicode="b" horiz-adv-x="569" d="M73,125C73,82 71,33 69,0l75,0l5,79l2,0C188,16 244,-11 314,-11C422,-11 532,75 532,248C532,394 448,494 327,494C249,494 193,460 162,406l-2,0l0,304l-87,0M160,280C160,294 162,306 165,317C183,383 239,425 298,425C393,425 443,342 443,245C443,134 389,59 296,59C232,59 180,101 164,162C161,172 160,183 160,194z"/> -<glyph unicode="c" horiz-adv-x="448" d="M403,83C378,72 345,60 295,60C199,60 127,129 127,241C127,341 187,424 298,424C346,424 379,412 400,401l20,67C396,481 350,494 298,494C140,494 38,385 38,236C38,88 133,-11 279,-11C344,-11 395,6 418,17z"/> -<glyph unicode="," horiz-adv-x="207" d="M78,-117C106,-70 150,41 174,126l-98,-10C65,43 38,-64 16,-124z"/> -<glyph unicode="d" horiz-adv-x="564" d="M403,710l0,-289l-2,0C379,459 330,494 255,494C138,494 37,396 38,235C38,88 129,-11 246,-11C325,-11 383,30 409,84l3,0l4,-84l78,0C492,33 490,82 490,125l0,585M403,203C403,189 402,177 399,165C383,100 329,60 270,60C176,60 127,141 127,239C127,345 181,425 272,425C338,425 386,379 399,324C402,313 403,298 403,287z"/> -<glyph unicode="e" horiz-adv-x="501" d="M462,226C464,236 465,249 465,267C465,356 424,494 265,494C124,494 38,380 38,234C38,88 127,-11 276,-11C353,-11 407,6 438,20l-16,63C390,69 351,58 288,58C199,58 124,107 122,226M123,289C130,350 168,431 258,431C357,431 381,344 380,289z"/> -<glyph unicode="h" horiz-adv-x="555" d="M73,0l88,0l0,292C161,308 162,321 167,334C184,381 228,421 285,421C368,421 397,356 397,278l0,-278l88,0l0,288C485,454 381,494 316,494C283,494 252,485 226,470C199,455 177,432 163,407l-2,0l0,303l-88,0z"/> -<glyph unicode="-" horiz-adv-x="307" d="M30,302l0,-64l247,0l0,64z"/> -<glyph unicode="i" horiz-adv-x="234" d="M161,0l0,484l-88,0l0,-484M117,675C84,675 62,650 62,620C62,590 83,566 115,566C150,566 171,590 171,620C171,651 149,675 117,675z"/> -<glyph unicode="k" horiz-adv-x="469" d="M160,710l-87,0l0,-710l87,0l0,182l45,50l166,-232l108,0l-213,285l186,199l-105,0l-143,-167C190,300 174,279 162,262l-2,0z"/> -<glyph unicode="l" horiz-adv-x="236" d="M73,0l88,0l0,710l-88,0z"/> -<glyph unicode="m" horiz-adv-x="834" d="M73,0l86,0l0,291C159,306 161,322 166,334C180,378 221,422 275,422C342,422 376,367 376,290l0,-290l86,0l0,299C462,315 465,330 469,343C485,385 523,422 574,422C644,422 679,367 679,273l0,-273l86,0l0,284C765,452 670,494 605,494C559,494 528,482 499,460C479,445 459,425 444,397l-2,0C421,454 371,494 306,494C225,494 180,451 153,405l-3,0l-4,79l-77,0C71,444 73,404 73,353z"/> -<glyph unicode="n" horiz-adv-x="555" d="M73,0l88,0l0,291C161,306 163,321 167,332C183,381 228,422 285,422C368,422 397,357 397,279l0,-279l88,0l0,288C485,454 381,494 314,494C234,494 178,449 154,404l-2,0l-5,80l-78,0C72,444 73,404 73,353z"/> -<glyph unicode="o" horiz-adv-x="549" d="M278,494C145,494 38,399 38,238C38,85 140,-11 270,-11C386,-11 511,67 511,246C511,393 417,494 278,494M276,428C380,428 421,325 421,243C421,134 358,55 274,55C188,55 128,135 128,241C128,332 173,428 276,428z"/> -<glyph unicode="p" horiz-adv-x="569" d="M73,-198l87,0l0,263l2,0C191,17 247,-11 311,-11C425,-11 532,75 532,249C532,395 444,494 326,494C247,494 189,460 154,401l-2,0l-5,83l-78,0C71,438 73,388 73,326M160,281C160,292 163,305 166,316C182,382 239,424 299,424C392,424 443,341 443,245C443,134 389,58 296,58C233,58 180,100 164,161C161,172 160,184 160,197z"/> -<glyph unicode="(" horiz-adv-x="284" d="M195,694C132,610 65,481 64,285C64,90 132,-38 195,-121l68,0C193,-21 138,106 138,284C138,466 190,595 263,694z"/> -<glyph unicode=")" horiz-adv-x="284" d="M88,-121C151,-37 218,91 219,287C219,483 151,612 88,694l-68,0C91,594 145,467 145,287C145,107 90,-22 20,-121z"/> -<glyph unicode="." horiz-adv-x="207" d="M110,-11C147,-11 171,16 171,52C171,89 147,115 112,115C77,115 52,88 52,52C52,16 76,-11 110,-11z"/> -<glyph unicode="?" horiz-adv-x="406" d="M220,192l-2,25C215,268 231,313 275,365C323,422 361,471 361,539C361,615 309,686 194,686C141,686 85,670 51,646l24,-63C100,602 140,614 176,614C239,613 271,579 271,528C271,483 246,444 201,391C151,331 133,271 139,218l2,-26M178,-11C215,-11 238,16 238,51C238,88 215,114 179,114C145,114 120,88 120,51C120,16 144,-11 178,-11z"/> -<glyph unicode="r" horiz-adv-x="327" d="M73,0l88,0l0,258C161,272 162,287 164,299C176,365 220,411 282,411C294,411 303,411 312,409l0,83C304,493 297,494 288,494C229,494 175,453 153,388l-3,0l-4,96l-77,0C72,439 73,390 73,333z"/> -<glyph unicode="s" horiz-adv-x="396" d="M40,23C74,3 123,-11 176,-11C289,-11 356,49 356,135C356,207 312,249 229,280C166,305 138,323 138,363C138,399 166,429 218,429C263,429 298,412 317,400l21,64C312,481 269,494 220,494C117,494 53,430 53,352C53,294 94,247 182,215C246,191 271,169 271,127C271,86 241,55 178,55C134,55 88,73 61,89z"/> -<glyph unicode="/" horiz-adv-x="343" d="M66,-39l280,725l-69,0l-278,-725z"/> -<glyph unicode=" " horiz-adv-x="212"/> -<glyph unicode="t" horiz-adv-x="331" d="M93,574l0,-90l-75,0l0,-67l75,0l0,-264C93,96 103,53 127,26C148,3 181,-11 222,-11C256,-11 283,-5 300,1l-4,67C283,64 269,62 245,62C196,62 179,96 179,156l0,261l126,0l0,67l-126,0l0,116z"/> -<glyph unicode="2" horiz-adv-x="513" d="M460,0l0,73l-291,0l0,2l51,48C357,255 444,352 444,472C444,565 385,661 245,661C171,661 106,632 62,595l28,-62C120,558 169,588 228,588C325,588 356,527 356,461C356,363 280,279 114,121l-69,-67l0,-54z"/> -<glyph unicode="u" horiz-adv-x="551" d="M478,484l-88,0l0,-296C390,171 387,155 382,143C366,103 325,62 266,62C187,62 158,125 158,217l0,267l-88,0l0,-283C70,32 161,-11 237,-11C323,-11 375,40 397,79l2,0l5,-79l78,0C479,38 478,82 478,133z"/> -<glyph unicode="v" horiz-adv-x="481" d="M13,484l184,-484l84,0l190,484l-92,0l-94,-271C269,168 255,128 244,88l-3,0C231,128 218,168 202,213l-95,271z"/> -<glyph unicode="x" horiz-adv-x="463" d="M16,484l164,-237l-172,-247l97,0l70,109C194,138 210,164 226,193l2,0C245,164 261,137 280,109l72,-109l99,0l-169,250l165,234l-96,0l-67,-103C267,355 251,330 235,302l-2,0C217,329 202,353 183,380l-69,104z"/> -<glyph unicode="y" horiz-adv-x="471" d="M9,484l178,-446C192,27 194,20 194,15C194,10 191,3 187,-6C166,-51 137,-85 113,-104C87,-126 58,-140 36,-147l22,-73C80,-216 122,-201 166,-164C226,-111 269,-27 332,139l132,345l-93,0l-96,-284C263,165 253,128 244,99l-2,0C234,128 222,166 210,198l-105,286z"/> -<glyph unicode="z" horiz-adv-x="428" d="M18,0l392,0l0,70l-282,0l0,2C150,96 169,121 190,148l216,281l0,55l-368,0l0,-70l262,0l0,-2C278,386 258,363 236,336l-218,-285z"/> -</font> - - <g> - <rect y="1.152" fill="#AAAAAA" stroke="#000000" width="256" height="36.887"/> - <text transform="matrix(1 0 0 1 27.7441 23.7046)" font-family="'MyriadPro-Regular'" font-size="14">Enter protected mode</text> -</g> -<g> - <rect y="45.642" fill="#AAAAAA" stroke="#000000" width="256" height="43.62"/> - <text transform="matrix(1 0 0 1 27.7441 71.5605)" font-family="'MyriadPro-Regular'" font-size="14">non-coherent HT enumeration</text> -</g> -<g> - <rect y="98.359" fill="#AAAAAA" stroke="#000000" width="256" height="60.15"/> - <text transform="matrix(1 0 0 1 27.7441 132.5435)" font-family="'MyriadPro-Regular'" font-size="14">coherent HT initialization</text> -</g> -<g> - <rect y="165.983" fill="#AAAAAA" stroke="#000000" width="256" height="68.421"/> - <text transform="matrix(1 0 0 1 27.7441 204.3022)" font-family="'MyriadPro-Regular'" font-size="14">Fallback / Normal?</text> -</g> -<g> - <rect y="243.893" fill="#AAAAAA" stroke="#000000" width="256" height="69.173"/> - <text transform="matrix(1 0 0 1 27.7441 282.5879)" font-family="'MyriadPro-Regular'" font-size="14">RAM initialization</text> -</g> -<g> - <rect y="410.747" fill="#AAAAAA" stroke="#000000" width="256" height="52.632"/> - <text transform="matrix(1 0 0 1 27.7441 432.7725)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Create external tables (coreboot table,</tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">ACPI, MP, PIRQ, DMI)</tspan></text> -</g> -<g> - <rect y="323.526" fill="#AAAAAA" stroke="#000000" width="256" height="77.443"/> - <text transform="matrix(1 0 0 1 27.7441 339.3154)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Resource Allocation (PCI, PCIe, I2C, SIO, </tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">CPU, mainboard...)</tspan></text> - <rect x="27.744" y="362.248" fill="#BCBCBC" width="228.256" height="38.722"/> -</g> -<g> - <rect y="473.781" fill="#AAAAAA" stroke="#000000" width="256" height="80.076"/> - <text transform="matrix(1 0 0 1 27.7441 497.4658)" font-family="'MyriadPro-Regular'" font-size="14">ELF / Payload Loader</text> - <rect x="27.744" y="507.993" fill="#BCBCBC" width="228.256" height="45.864"/> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7 - 132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439 "/> - </g> - <polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181 "/> - <polygon fill="#231F20" points="131.152,57.643 132.28,59.108 118.41,57.093 117.644,56.096 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7 - 132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439 "/> - </g> - <polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181 "/> - <polygon fill="#231F20" points="131.152,107.643 132.28,109.108 118.41,107.093 117.644,106.096 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041 - 132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78 "/> - </g> - <polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522 "/> - <polygon fill="#231F20" points="131.152,177.983 132.28,179.449 118.41,177.434 117.644,176.437 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467 - 132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207 "/> - </g> - <polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948 "/> - <polygon fill="#231F20" points="131.152,253.41 132.28,254.875 118.41,252.86 117.644,251.863 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468 - 132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207 "/> - </g> - <polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948 "/> - <polygon fill="#231F20" points="131.152,329.41 132.28,330.876 118.41,328.86 117.643,327.864 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327 - 132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066 "/> - </g> - <polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808 "/> - <polygon fill="#231F20" points="131.152,422.27 132.28,423.735 118.41,421.72 117.644,420.724 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<g> - <g> - <g> - <g> - <g> - <g> - <g> - <g> - <polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608 - 132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347 "/> - </g> - <polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089 "/> - <polygon fill="#231F20" points="131.152,478.551 132.28,480.017 118.41,478.001 117.643,477.004 "/> - </g> - </g> - </g> - </g> - </g> - </g> -</g> -<text transform="matrix(1 0 0 1 59.3232 385.7627)" font-family="'MyriadPro-Regular'" font-size="14">Drivers</text> -<text transform="matrix(1 0 0 1 55.564 535.3789)" font-family="'MyriadPro-Regular'" font-size="14">Linux, FILO, SeaBIOS, ...</text> -</svg> diff --git a/Documentation/core/00-index.md b/Documentation/core/00-index.md new file mode 100644 index 0000000..569c86e --- /dev/null +++ b/Documentation/core/00-index.md @@ -0,0 +1,11 @@ +--- +title: Core Manual +url: core +type: index +date: "2016-10-01" +weight: 0 +categories: + - "core" +tags: + - "core" +--- diff --git a/Documentation/core/10-build_system.md b/Documentation/core/10-build_system.md new file mode 100644 index 0000000..d509900 --- /dev/null +++ b/Documentation/core/10-build_system.md @@ -0,0 +1,98 @@ +--- +title: The coreboot build system +url: core/build_system +weight: 10 +categories: + - "core" +tags: + - "core" +menu: + main: + parent: Core Manual + identifier: Build_System + weight: 10 +--- + +(this document is still incomplete and will be filled in over time) + +## General operation +The coreboot build system is based on GNU make but extends it significantly +to the point of providing its own custom language. +The overhead of learning this new syntax is (hopefully) offset by its lower +complexity. + +The build system is defined in the toplevel `Makefile` and `toolchain.inc` +and is supposed to be generic (and is in fact used with a number of other +projects). Project specific configuration should reside in files called +`Makefile.inc`. + +In general, the build system provides a number of "classes" that describe +various parts of the build. These cover the various build targets in coreboot +such as the stages, subdirectories with more source code, and the general +addition of files. + +Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used +by filling in a variable of that name followed by `-y` (eg. `romstage-y`, +`subdirs-y`, `cbfs-files-y`). +The `-y` suffix allows a simple interaction with our Kconfig build +configuration system: Kconfig options are available as variables starting +with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty. + +This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to +`class` depending on the choice for `FOO`. + +## classes +Classes can be defined as required. `subdirs` is handled internally since +it's parsed per subdirectory to add further directories to the rule set. + +TODO: explain how to create new classes and how to evaluate them. + +### subdirs +`subdirs` contains subdirectories (relative to the current directory) that +should also be handled by the build system. The build system expects these +directories to contain a file called `Makefile.inc`. + +Subdirectories are not read at the point where the `subdirs` statement +resides but later, after the current directory is handled (and potentially +others, too). + +### cbfs-files +This class is used to add files to the final CBFS image. Since several more +options need to be maintained than can comfortably fit in that single +variable, additional variables are used. + +`cbfs-files-y` contains the file name used in the CBFS image (called `foo` +here). Additional options are added in `foo-$(option)` variables. The +supported options are: + +* `file`: The on-disk file to add as `foo` (required) +* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary` (required) +* `compression`: Can be `none` or `lzma` (default: none) +* `position`: An absolute position constraint for the placement of the file (default: none) +* `align`: Minimum alignment for the file (default: none) +* `options`: Additional cbfstool options (default: none) + +`position` and `align` are mutually exclusive. + +#### FMAP region support +With the addition of FMAP flash partitioning support to coreboot, there was a +need to extend the specification of files to provide more precise control +which regions should contain which files, and even change some flags based on +the region. + +Since FMAP policies depend on features using FMAP, that's kept separate from +the cbfs-files class. + +The `position` and `align` options for file `foo` can be overwritten for a +region `REGION` using `foo-REGION-position` and `foo-REGION-align`. + +The regions that each file should end in can be defined by overriding a +function called `regions-for-file` that's called as +`$(call regions-for-file,$(filename))` and should return a comma-separated +list of regions, such as `REGION1,REGION2,REGION3`. + +The default implementation just returns `COREBOOT` (the default region) for +all files. + +vboot provides its own implementation of `regions-for-file` that can be used +as reference in `src/vboot/Makefile.inc`. diff --git a/Documentation/core/20-gerrit_guidelines.md b/Documentation/core/20-gerrit_guidelines.md new file mode 100644 index 0000000..ce6f797 --- /dev/null +++ b/Documentation/core/20-gerrit_guidelines.md @@ -0,0 +1,125 @@ +--- +title: Gerrit guidelines +url: core/gerrit_guidelines +weight: 20 +categories: + - "core" +tags: + - "core" +menu: + main: + parent: Core Manual + identifier: Gerrit_Guidelines + weight: 20 +--- + +The following rules are the requirements for behavior in the coreboot codebase in gerrit. These have mainly been unwritten rules up to this point, and should be familiar to most users who have been active in coreboot for a period of time. Following these rules will help reduce friction in the community. + +Note that as with many rules, there are exceptions. Some have been noted in the 'More Detail' section. If you feel there is an exception not listed here, please discuss it in the mailing list to get this document updated. Don't just assume that it's okay, even if someone on IRC says it is. + +## Summary: + +These are the expectations for committing, reviewing, and submitting code into coreboot git and gerrit. While breaking individual rules may not have immediate consequences, the coreboot leadership may act on repeated or flagrant violations with or without notice. + +- Don't violate the licenses. +- Let non-trivial patches sit in a review state for at least 24 hours before submission. +- Try to coordinate with platform maintainers when making changes to platforms. +- If you give a patch a -2, you are responsible for giving concrete recommendations for what could be changed to resolve the issue the patch addresses. +- Don't modify other people's patches without their consent. +- Be respectful to others when commenting. +- Don't submit patches that you know will break other platforms. + +## More detail: + +- Don't violate the licenses. If you're submitting code that you didn't write yourself, make sure the license is compatible with the license of the project you're submitting the changes to. If you're submitting code that you wrote that might be owned by your employer, make sure that your employer is aware and you are authorized to submit the code. For clarification, see the Developer's Certificate of Origin in the coreboot [Signed-off-by policy](http://www.coreboot.org/Development_Guidelines#Sign-off_Procedure). + +- 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 overlook something like accidentally updating file permissions or git submodule commit IDs. Let someone else review the patch. An exception to this would be if two people worked in the patch together. If both +2 the patch, that is acceptable, as each is giving a +2 to the other's work. + +- Try to coordinate with platform maintainers and other significant contributors to the code when making changes to platforms. The platform maintainers are the users who initially pushed the code for that platform, as well as users who have made significant changes to a platform. To find out who maintains a piece of code, please use util/scripts/maintainers.go or refer to the original author of the code in git log. + +- If you give a patch a -2, you are responsible for giving concrete recommendations for what could be changed to resolve the issue the patch addresses. If you feel strongly that a patch should NEVER be merged, you are responsible for defending your position and listening to other points of view. Giving a -2 and walking away is not acceptable, and may cause your -2 to be removed by the coreboot leadership after no less than a week. A notification that the -2 will be removed unless there is a response will be sent out at least 2 days before it is removed. + +- Don't modify other people's patches unless you have coordinated this with the owner of that patch. Not only is this considered rude, but your changes could be unintentionally lost. An exception to this would be for patches that have not been updated for more than 90 days. In that case, the patch can be taken over if the original author does not respond to requests for updates. Alternatively, a new patch can be pushed with the original content, and both patches should be updated to reference the other. + +- Be respectful to others when commenting on patches. Comments should be kept to the code, and should be kept in a polite tone. We are a worldwide community and English is a difficult language. Assume your colleagues are intelligent and do not intend disrespect. Resist the urge to retaliate against perceived verbal misconduct, such behavior is not conducive to getting patches merged. + +- Don't submit code that you know will break other platforms. If your patch affects code that is used by other platforms, it should be compatible with those platforms. While it would be nice to update any other platforms, you must at least provide a path that will allow other platforms to continue working. + +## Recommendations for gerrit activity: + +These guidelines are less strict than the ones listed above. These are more of the "good idea" variety. You are requested to follow the below guidelines, but there will probably be no actual consequences if they're not followed. That said, following the recommendations below will speed up review of your patches, and make the members of the community do less work. + +- Each patch should be kept to one logical change, which should be described in the title of the patch. Unrelated changes should be split out into separate patches. Fixing whitespace on a line you're editing is reasonable. Fixing whitespace around the code you're working on should be a separate 'cleanup' patch. Larger patches that touch several areas are fine, so long as they are one logical change. Adding new chips and doing code cleanup over wide areas are two examples of this. + +- Test your patches before submitting them to gerrit. It's also appreciated if you add a line to the commit message describing how the patch was tested. This prevents people from having to ask whether and how the patch was tested. Examples of this sort of comment would be 'TEST=Built platform' or 'Tested by building and booting platform'. Stating that the patch was not tested is also fine, although you might be asked to do some testing in cases where that would be reasonable. + +- Take advantage of the lint tools to make sure your patches don't contain trivial mistakes. By running 'make gitconfig', the lint-stable tools are automatically put in place and will test your patches before they are committed. As a violation of these tools will cause the jenkins build test to fail, it's to your advantage to test this before pushing to gerrit. + +- Don't submit patch trains longer than around 20 patches unless you understand how to manage long patch trains. Long patch trains can become difficult to handle and tie up the build servers for long periods of time if not managed well. Rebasing a patch train over and over as you fix earlier patches in the train can hide comments, and make people review the code multiple times to see if anything has changed between revisions. When pushing long patch trains, it is recommended to only push the full patch train once - the initial time, and only to rebase three or four patches at a time. + +- Run 'make what-jenkins-does' locally on patch trains before submitting. This helps verify that the patch train won't tie up the jenkins builders for no reason if there are failing patches in the train. For running parallel builds, you can specify the number of cores to use by setting the the CPUS environment variable. Example: + + ```sh + make what-jenkins-does CPUS=8 + ``` + +- Use a topic when pushing a train of patches. This groups the commits together so people can easily see the connection at the top level of gerrit. Topics can be set for individual patches in gerrit by going into the patch and clicking on the icon next to the topic line. Topics can also be set when you push the patches into gerrit. For example, to push a set of commits with the the i915-kernel-x60 set, use the command: + + ```sh + 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 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 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 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 draft, use the command: + + ```sh + 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 request to fix spelling or 'trivial' issues, it's generally easy to handle in gerrit's built-in editor. If you do use the built-in editor, remember to get that change to your local copy before re-pushing. It's also acceptable to add fixes for these sorts of comments to another patch, but it's recommended that that patch be pushed to gerrit before the initial patch gets submitted. + +- Consider breaking up large individual patches into smaller patches grouped by areas. This makes the patches easier to review, but increases the number of patches. The way you want to handle this is a personal decision, as long as each patch is still one logical change. + +- If you have an interest in a particular area or mainboard, set yourself up as a 'maintainer' of that area by adding yourself to the MAINTAINERS file in the coreboot root directory. Eventually, this should automatically add you as a reviewer when an area that you're listed as a maintainer is changed. + +- Submit mainboards that you're working on to the board-status repo. This helps others and shows that these mainboards are currently being maintained. At some point, boards that are not up to date in the board-status repo will probably end up getting removed from the coreboot master branch. + +- Abandon patches that are no longer useful, or that you don't intend to keep working on to get submitted. + +- Bring attention to patches that you would like reviewed. Add reviewers, ask for reviewers on IRC or even just rebase it against the current codebase to bring it to the top of the gerrit list. If you're not sure who would be a good reviewer, look in the MAINTAINERS file or git history of the files that you've changed, and add those people. + +- Familiarize yourself with the coreboot [commit message guidelines](http://www.coreboot.org/Git#Commit_messages), before pushing patches. This will help to keep annoying requests to fix your commit message to a minimum. + +- If there have been comments or discussion on a patch, verify that the comments have been addressed before giving a +2\. If you feel that a comment is invalid, please respond to that comment instead of just ignoring it. + +- Be conscientious when reviewing patches. As a reviewer who approves (+2) a patch, you are responsible for the patch and the effect it has on the codebase. In the event that the patch breaks things, you are expected to be actively involved in the cleanup effort. This means you shouldn't +2 a patch just because you trust the author of a patch - Make sure you understand what the implications of a patch might be, or leave the review to others. Partial reviews, reviewing code style, for example, can be given a +1 instead of a +2\. This also applies if you think the patch looks good, but may not have the experience to know if there may be unintended consequences. + +- If there is still ongoing discussion to a patch, try to wait for a conclusion to the discussion before submitting it to the tree. If you feel that someone is just bikeshedding, maybe just state that and give a time that the patch will be submitted if no new objections are raised. + +- When working with patch trains, for minor requests it's acceptable to create a fix addressing a comment in another patch at the end of the patch train. This minimizes rebases of the patch train while still addressing the request. For major problems where the change doesn't work as intended or breaks other platforms, the change really needs to go into the original patch. + +- When bringing in a patch from another git repo, update the original git/gerrit tags by prepending the lines with 'Original-'. Marking the original text this way makes it much easier to tell what changes happened in which repository. This applies to these lines, not the actual commit message itself: + +``` + Commit-Id: + Change-Id: + Signed-off-by: + Reviewed-on: + Tested-by: + Reviewed-by: +``` + +The script 'util/gitconfig/rebase.sh' can be used to help automate this. Other tags such as 'Commit-Queue' can simply be removed. + +## Expectations contributors should have: + +- Don't expect that people will review your patch unless you ask them to. Adding other people as reviewers is the easiest way. Asking for reviews for individual patches in the IRC channel, or by sending a direct request to an individual through your favorite messenger is usually the best way to get a patch reviewed quickly. + +- Don't expect that your patch will be submitted immediately after getting a +2\. As stated previously, non-trivial patches should wait at least 24 hours before being submitted. That said, if you feel that your patch or series of patches has been sitting longer than needed, you can ask for it to be submitted on IRC, or comment that it's ready for submission in the patch. This will move it to the top of the list where it's more likely to be noticed and acted upon. + +- Reviews are about the code. It's easy to take it personally when someone is criticising your code, but the whole idea is to get better code into our codebase. Again, this also applies in the other direction: review code, criticize code, but don't make it personal. + +Requests for clarification and suggestions for updates to these guidelines should be sent to the coreboot mailing list at [coreboot@coreboot.org](mailto:coreboot@coreboot.org). diff --git a/Documentation/core/30-submodules.md b/Documentation/core/30-submodules.md new file mode 100644 index 0000000..cf2d05c --- /dev/null +++ b/Documentation/core/30-submodules.md @@ -0,0 +1,46 @@ +--- +title: Git submodules +url: core/submodules +weight: 30 +categories: + - "core" +tags: + - "core" +menu: + main: + parent: Core Manual + identifier: Submodules + weight: 30 +--- + +coreboot uses git submodules to keep certain parts of the tree separate, with two major use cases: + +First, we use a vendor tool by NVIDIA for systems based on their SoC and since they publish it through git, we can just import it into our tree using submodules. + +Second, lots of boards these days require binaries and we want to keep them separate from coreboot proper to clearly delineate shiny Open Source from ugly blobs. Since we don't want to impose blobs on users who really don't need them, that repository is only downloaded and checked out on explicit request. + +## Handling submodules + +For the most part, submodules should be automatically checked out on the first execution of the coreboot Makefile. + +To manually fetch all repositories (eg. when you want to prepare the tree for archiving, or to use it without network access), run + +``` +$ git submodule update --init --checkout +``` + +This also checks out the binaries below `3rdparty/` + +## Mirroring coreboot + +When running a coreboot mirror to checkout from, for full operation, you should also mirror the blobs and nvidia-cbootimage repository, and place them in the same directory as the coreboot repository mirror. + +That is, when residing in coreboot's repository, `cd ../blobs.git` should move you to the blobs repository. + +With that, no matter what the URL of your coreboot repository is, the git client (of a sufficiently new version) is able to pick up the other repositories transparently. + +## Minimum requirements + +git needs to be able to handle relative paths to submodule repositories, and it needs to know about non-automatic submodules. + +For these features, we require git version 1.7.6.1 or newer. diff --git a/Documentation/coreboot_logo.png b/Documentation/coreboot_logo.png deleted file mode 100644 index dde1aa6..0000000 Binary files a/Documentation/coreboot_logo.png and /dev/null differ diff --git a/Documentation/endverbatim.tex b/Documentation/endverbatim.tex deleted file mode 100644 index f832f3f..0000000 --- a/Documentation/endverbatim.tex +++ /dev/null @@ -1 +0,0 @@ -\end{verbatim} diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt deleted file mode 100644 index 896ec93..0000000 --- a/Documentation/gcov.txt +++ /dev/null @@ -1,227 +0,0 @@ -This patch contains our local modifications for gcov-io.h and libgcov.c. -The file gcov-iov.h is taken from a gcc build (produced at compile -time). The file gcov-io.c is unchanged. - ---- gcc-4.7.2/gcc/gcov-io.h 2011-12-04 10:27:19.000000000 -0800 -+++ coreboot/src/lib/gcov-io.h 2013-01-12 16:45:57.000000000 -0800 -@@ -163,6 +163,24 @@ - #ifndef GCC_GCOV_IO_H - #define GCC_GCOV_IO_H - -+#ifdef __COREBOOT__ -+#define GCOV_LINKAGE /* nothing */ -+/* We need the definitions for -+ BITS_PER_UNIT and -+ LONG_LONG_TYPE_SIZE -+ They are defined in gcc/defaults.h and gcc/config/<arch_depend_files> -+ (like, gcc/config/i386/i386.h). And it can be overridden by setting -+ in build scripts. Here I hardcoded the value for x86. */ -+#define BITS_PER_UNIT 8 -+#define LONG_LONG_TYPE_SIZE 64 -+ -+/* There are many gcc_assertions. Set the vaule to 1 if we want a warning -+ message if the assertion fails. */ -+#ifndef ENABLE_ASSERT_CHECKING -+#define ENABLE_ASSERT_CHECKING 1 -+#endif -+#endif /* __COREBOOT__ */ -+ - #if IN_LIBGCOV - /* About the target */ - -@@ -232,7 +250,9 @@ - is not also used in a DSO. */ - #if IN_LIBGCOV - -+#ifndef __COREBOOT__ - #include "tconfig.h" -+#endif /* __COREBOOT__ */ - - #define gcov_var __gcov_var - #define gcov_open __gcov_open -@@ -455,8 +475,10 @@ - /* Register a new object file module. */ - extern void __gcov_init (struct gcov_info *) ATTRIBUTE_HIDDEN; - -+#ifndef __COREBOOT__ - /* Called before fork, to avoid double counting. */ - extern void __gcov_flush (void) ATTRIBUTE_HIDDEN; -+#endif - - /* The merge function that just sums the counters. */ - extern void __gcov_merge_add (gcov_type *, unsigned) ATTRIBUTE_HIDDEN; ---- gcc-4.7.2/libgcc/libgcov.c 2012-01-11 10:50:21.000000000 -0800 -+++ coreboot/src/lib/libgcov.c 2013-01-16 09:45:11.000000000 -0800 -@@ -25,12 +25,41 @@ - see the files COPYING3 and COPYING.RUNTIME respectively. If not, see - <http://www.gnu.org/licenses/>. */ - -+#define __COREBOOT__ -+#ifdef __COREBOOT__ -+#include <stdlib.h> -+#include <string.h> -+#include <console/console.h> -+#include <assert.h> -+typedef s32 pid_t; -+#define gcc_assert(x) ASSERT(x) -+#define fprintf(file, x...) printk(BIOS_ERR, x) -+#define alloca(size) __builtin_alloca (size) -+#include "gcov-glue.c" -+ -+/* Define MACROs to be used by coreboot compilation. */ -+# define L_gcov -+# define L_gcov_interval_profiler -+# define L_gcov_pow2_profiler -+# define L_gcov_one_value_profiler -+# define L_gcov_indirect_call_profiler -+# define L_gcov_average_profiler -+# define L_gcov_ior_profiler -+ -+# define HAVE_CC_TLS 0 -+# define __GCOV_KERNEL__ -+ -+# define IN_LIBGCOV 1 -+# define IN_GCOV 0 -+#else /* __COREBOOT__ */ - #include "tconfig.h" - #include "tsystem.h" - #include "coretypes.h" - #include "tm.h" - #include "libgcc_tm.h" -+#endif /* __COREBOOT__ */ - -+#ifndef __COREBOOT__ - #if defined(inhibit_libc) - #define IN_LIBGCOV (-1) - #else -@@ -41,6 +70,7 @@ - #define GCOV_LINKAGE /* nothing */ - #endif - #endif -+#endif /* __COREBOOT__ */ - #include "gcov-io.h" - - #if defined(inhibit_libc) -@@ -68,12 +98,17 @@ - - #else - -+#ifndef __COREBOOT__ - #include <string.h> - #if GCOV_LOCKED - #include <fcntl.h> - #include <errno.h> - #include <sys/stat.h> - #endif -+#else -+void __gcov_merge_add(gcov_type *counters __attribute__ ((unused)), -+ unsigned n_counters __attribute__ ((unused))) {} -+#endif /* __COREBOOT__ */ - - #ifdef L_gcov - #include "gcov-io.c" -@@ -99,6 +134,10 @@ - static int - create_file_directory (char *filename) - { -+#ifdef __COREBOOT__ -+ (void) filename; -+ return 0; -+#else - #if !defined(TARGET_POSIX_IO) && !defined(_WIN32) - (void) filename; - return -1; -@@ -137,6 +176,7 @@ - }; - return 0; - #endif -+#endif - } - - static struct gcov_fn_buffer * -@@ -279,7 +319,7 @@ - struct gcov_ctr_summary *cs_ptr; - const struct gcov_ctr_info *ci_ptr; - unsigned t_ix; -- int f_ix; -+ int f_ix = 0; - gcov_unsigned_t c_num; - const char *gcov_prefix; - int gcov_prefix_strip = 0; -@@ -329,6 +369,7 @@ - } - } - -+#ifndef __COREBOOT__ - { - /* Check if the level of dirs to strip off specified. */ - char *tmp = getenv("GCOV_PREFIX_STRIP"); -@@ -352,6 +393,7 @@ - prefix_length--; - } - else -+#endif - prefix_length = 0; - - /* If no prefix was specified and a prefix stip, then we assume -@@ -696,8 +738,10 @@ - if (filename_length > gcov_max_filename) - gcov_max_filename = filename_length; - -+#ifndef __COREBOOT__ - if (!gcov_list) - atexit (gcov_exit); -+#endif - - info->next = gcov_list; - gcov_list = info; -@@ -767,14 +811,15 @@ - - #ifdef L_gcov_merge_single - /* The profile merging function for choosing the most common value. -- It is given an array COUNTERS of N_COUNTERS old counters and it -- reads the same number of counters from the gcov file. The counters -- are split into 3-tuples where the members of the tuple have -- meanings: -- -- -- the stored candidate on the most common value of the measured entity -- -- counter -- -- total number of evaluations of the value */ -+ * It is given an array COUNTERS of N_COUNTERS old counters and it -+ * reads the same number of counters from the gcov file. The counters -+ * are split into 3-tuples where the members of the tuple have -+ * meanings: -+ * -+ * -- the stored candidate on the most common value of the measured entity -+ * -- counter -+ * -- total number of evaluations of the value -+ */ - void - __gcov_merge_single (gcov_type *counters, unsigned n_counters) - { -@@ -805,15 +850,16 @@ - - #ifdef L_gcov_merge_delta - /* The profile merging function for choosing the most common -- difference between two consecutive evaluations of the value. It is -- given an array COUNTERS of N_COUNTERS old counters and it reads the -- same number of counters from the gcov file. The counters are split -- into 4-tuples where the members of the tuple have meanings: -- -- -- the last value of the measured entity -- -- the stored candidate on the most common difference -- -- counter -- -- total number of evaluations of the value */ -+ * difference between two consecutive evaluations of the value. It is -+ * given an array COUNTERS of N_COUNTERS old counters and it reads the -+ * same number of counters from the gcov file. The counters are split -+ * into 4-tuples where the members of the tuple have meanings: -+ * -+ * -- the last value of the measured entity -+ * -- the stored candidate on the most common difference -+ * -- counter -+ * -- total number of evaluations of the value -+ */ - void - __gcov_merge_delta (gcov_type *counters, unsigned n_counters) - { diff --git a/Documentation/gerrit_guidelines.md b/Documentation/gerrit_guidelines.md deleted file mode 100644 index 1833b0a..0000000 --- a/Documentation/gerrit_guidelines.md +++ /dev/null @@ -1,277 +0,0 @@ -coreboot Gerrit Etiquette and Guidelines -======================================== - -The following rules are the requirements for behavior in the coreboot -codebase in gerrit. These have mainly been unwritten rules up to this -point, and should be familiar to most users who have been active in -coreboot for a period of time. Following these rules will help reduce -friction in the community. - -Note that as with many rules, there are exceptions. Some have been noted -in the 'More Detail' section. If you feel there is an exception not listed -here, please discuss it in the mailing list to get this document updated. -Don't just assume that it's okay, even if someone on IRC says it is. - - -Summary: --------- -These are the expectations for committing, reviewing, and submitting code -into coreboot git and gerrit. While breaking individual rules may not have -immediate consequences, the coreboot leadership may act on repeated or -flagrant violations with or without notice. - -* Don't violate the licenses. -* Let non-trivial patches sit in a review state for at least 24 hours -before submission. -* Try to coordinate with platform maintainers when making changes to -platforms. -* If you give a patch a -2, you are responsible for giving concrete -recommendations for what could be changed to resolve the issue the patch -addresses. -* Don't modify other people's patches without their consent. -* Be respectful to others when commenting. -* Don’t submit patches that you know will break other platforms. - - -More detail: ------------- -* Don't violate the licenses. If you're submitting code that you didn't -write yourself, make sure the license is compatible with the license of the -project you're submitting the changes to. If you’re submitting code that -you wrote that might be owned by your employer, make sure that your -employer is aware and you are authorized to submit the code. For -clarification, see the Developer's Certificate of Origin in the coreboot -[Signed-off-by policy](http://www.coreboot.org/Development_Guidelines#Sign-off_Procedure). - -* 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 -overlook something like accidentally updating file permissions or git -submodule commit IDs. Let someone else review the patch. An exception to -this would be if two people worked in the patch together. If both +2 the -patch, that is acceptable, as each is giving a +2 to the other's work. - -* Try to coordinate with platform maintainers and other significant -contributors to the code when making changes to platforms. The platform -maintainers are the users who initially pushed the code for that platform, -as well as users who have made significant changes to a platform. To find -out who maintains a piece of code, please use util/scripts/maintainers.go -or refer to the original author of the code in git log. - -* If you give a patch a -2, you are responsible for giving concrete -recommendations for what could be changed to resolve the issue the patch -addresses. If you feel strongly that a patch should NEVER be merged, you -are responsible for defending your position and listening to other points -of view. Giving a -2 and walking away is not acceptable, and may cause your - -2 to be removed by the coreboot leadership after no less than a week. A - notification that the -2 will be removed unless there is a response will - be sent out at least 2 days before it is removed. - -* Don't modify other people's patches unless you have coordinated this with -the owner of that patch. Not only is this considered rude, but your changes -could be unintentionally lost. An exception to this would be for patches -that have not been updated for more than 90 days. In that case, the patch -can be taken over if the original author does not respond to requests for -updates. Alternatively, a new patch can be pushed with the original -content, and both patches should be updated to reference the other. - -* Be respectful to others when commenting on patches. Comments should -be kept to the code, and should be kept in a polite tone. We are a -worldwide community and English is a difficult language. Assume your -colleagues are intelligent and do not intend disrespect. Resist the urge to -retaliate against perceived verbal misconduct, such behavior is not -conducive to getting patches merged. - -* Don’t submit code that you know will break other platforms. If your patch -affects code that is used by other platforms, it should be compatible with -those platforms. While it would be nice to update any other platforms, you -must at least provide a path that will allow other platforms to continue -working. - - -Recommendations for gerrit activity: ------------------------------------- -These guidelines are less strict than the ones listed above. These are more -of the “good idea” variety. You are requested to follow the below -guidelines, but there will probably be no actual consequences if they’re -not followed. That said, following the recommendations below will speed up -review of your patches, and make the members of the community do less work. - -* Each patch should be kept to one logical change, which should be -described in the title of the patch. Unrelated changes should be split out -into separate patches. Fixing whitespace on a line you’re editing is -reasonable. Fixing whitespace around the code you’re working on should be a -separate ‘cleanup’ patch. Larger patches that touch several areas are fine, -so long as they are one logical change. Adding new chips and doing code -cleanup over wide areas are two examples of this. - -* Test your patches before submitting them to gerrit. It's also appreciated -if you add a line to the commit message describing how the patch was -tested. This prevents people from having to ask whether and how the patch -was tested. Examples of this sort of comment would be ‘TEST=Built -platform’ or ‘Tested by building and booting platform’. Stating that the -patch was not tested is also fine, although you might be asked to do some -testing in cases where that would be reasonable. - -* Take advantage of the lint tools to make sure your patches don’t contain -trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are -automatically put in place and will test your patches before they are -committed. As a violation of these tools will cause the jenkins build test -to fail, it’s to your advantage to test this before pushing to gerrit. - -* Don't submit patch trains longer than around 20 patches unless you -understand how to manage long patch trains. Long patch trains can become -difficult to handle and tie up the build servers for long periods of time -if not managed well. Rebasing a patch train over and over as you fix -earlier patches in the train can hide comments, and make people review the -code multiple times to see if anything has changed between revisions. When -pushing long patch trains, it is recommended to only push the full patch -train once - the initial time, and only to rebase three or four patches at -a time. - -* Run 'make what-jenkins-does' locally on patch trains before submitting. -This helps verify that the patch train won’t tie up the jenkins builders -for no reason if there are failing patches in the train. For running -parallel builds, you can specify the number of cores to use by setting the -the CPUS environment variable. Example: - make what-jenkins-does CPUS=8 - -* Use a topic when pushing a train of patches. This groups the commits -together so people can easily see the connection at the top level of -gerrit. Topics can be set for individual patches in gerrit by going into -the patch and clicking on the icon next to the topic line. Topics can also -be set when you push the patches into gerrit. For example, to push a set of -commits with the 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 -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 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 -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 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 -request to fix spelling or 'trivial' issues, it’s generally easy to handle -in gerrit’s built-in editor. If you do use the built-in editor, remember to -get that change to your local copy before re-pushing. It's also acceptable -to add fixes for these sorts of comments to another patch, but it's -recommended that that patch be pushed to gerrit before the initial patch -gets submitted. - -* Consider breaking up large individual patches into smaller patches -grouped by areas. This makes the patches easier to review, but increases -the number of patches. The way you want to handle this is a personal -decision, as long as each patch is still one logical change. - -* If you have an interest in a particular area or mainboard, set yourself -up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS -file in the coreboot root directory. Eventually, this should automatically -add you as a reviewer when an area that you’re listed as a maintainer is -changed. - -* Submit mainboards that you’re working on to the board-status repo. This -helps others and shows that these mainboards are currently being -maintained. At some point, boards that are not up to date in the -board-status repo will probably end up getting removed from the coreboot -master branch. - -* Abandon patches that are no longer useful, or that you don’t intend to -keep working on to get submitted. - -* Bring attention to patches that you would like reviewed. Add reviewers, -ask for reviewers on IRC or even just rebase it against the current -codebase to bring it to the top of the gerrit list. If you’re not sure who -would be a good reviewer, look in the MAINTAINERS file or git history of -the files that you’ve changed, and add those people. - -* Familiarize yourself with the coreboot [commit message -guidelines](http://www.coreboot.org/Git#Commit_messages), before pushing -patches. This will help to keep annoying requests to fix your commit -message to a minimum. - -* If there have been comments or discussion on a patch, verify that the -comments have been addressed before giving a +2. If you feel that a comment -is invalid, please respond to that comment instead of just ignoring it. - -* Be conscientious when reviewing patches. As a reviewer who approves (+2) -a patch, you are responsible for the patch and the effect it has on the -codebase. In the event that the patch breaks things, you are expected to -be actively involved in the cleanup effort. This means you shouldn’t +2 a -patch just because you trust the author of a patch - Make sure you -understand what the implications of a patch might be, or leave the review -to others. Partial reviews, reviewing code style, for example, can be given -a +1 instead of a +2. This also applies if you think the patch looks good, -but may not have the experience to know if there may be unintended -consequences. - -* If there is still ongoing discussion to a patch, try to wait for a -conclusion to the discussion before submitting it to the tree. If you feel -that someone is just bikeshedding, maybe just state that and give a time -that the patch will be submitted if no new objections are raised. - -* When working with patch trains, for minor requests it’s acceptable to -create a fix addressing a comment in another patch at the end of the patch -train. This minimizes rebases of the patch train while still addressing the -request. For major problems where the change doesn’t work as intended or -breaks other platforms, the change really needs to go into the original -patch. - -* When bringing in a patch from another git repo, update the original -git/gerrit tags by prepending the lines with 'Original-'. Marking -the original text this way makes it much easier to tell what changes -happened in which repository. This applies to these lines, not the actual -commit message itself: - Commit-Id: - Change-Id: - Signed-off-by: - Reviewed-on: - Tested-by: - Reviewed-by: -The script 'util/gitconfig/rebase.sh' can be used to help automate this. -Other tags such as 'Commit-Queue' can simply be removed. - - -Expectations contributors should have: --------------------------------------- -* Don't expect that people will review your patch unless you ask them to. -Adding other people as reviewers is the easiest way. Asking for reviews for -individual patches in the IRC channel, or by sending a direct request to an -individual through your favorite messenger is usually the best way to get a -patch reviewed quickly. - -* Don't expect that your patch will be submitted immediately after getting -a +2. As stated previously, non-trivial patches should wait at least 24 -hours before being submitted. That said, if you feel that your patch or -series of patches has been sitting longer than needed, you can ask for it -to be submitted on IRC, or comment that it's ready for submission in the -patch. This will move it to the top of the list where it's more likely to -be noticed and acted upon. - -* Reviews are about the code. It's easy to take it personally when someone -is criticising your code, but the whole idea is to get better code into our -codebase. Again, this also applies in the other direction: review code, -criticize code, but don’t make it personal. - - -Requests for clarification and suggestions for updates to these guidelines -should be sent to the coreboot mailing list at <coreboot(a)coreboot.org>. diff --git a/Documentation/hypertransport.svg b/Documentation/hypertransport.svg deleted file mode 100644 index 757e7f4..0000000 --- a/Documentation/hypertransport.svg +++ /dev/null @@ -1,59 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" - width="256px" height="512px" viewBox="0 0 256 512" enable-background="new 0 0 256 512" xml:space="preserve"> -<font horiz-adv-x="2048"> -<font-face font-family="ArialMT" units-per-em="2048" underline-position="-217" underline-thickness="150"/> -<missing-glyph horiz-adv-x="1536" d="M256,0l0,1280l1024,0l0,-1280M288,32l960,0l0,1216l-960,0z"/> -<glyph unicode=" " horiz-adv-x="569"/> -<glyph unicode="(" horiz-adv-x="682" d="M479,-431C380,-306 296,-159 227,9C158,177 124,351 124,531C124,690 150,842 201,987C261,1156 354,1324 479,1491l129,0C527,1352 474,1253 448,1194C407,1102 375,1006 352,906C323,781 309,656 309,530C309,209 409,-111 608,-431z"/> -<glyph unicode=")" horiz-adv-x="682" d="M253,-431l-129,0C323,-111 423,209 423,530C423,655 409,780 380,903C357,1003 326,1099 285,1191C259,1251 205,1351 124,1491l129,0C378,1324 471,1156 531,987C582,842 608,690 608,531C608,351 574,177 505,9C436,-159 352,-306 253,-431z"/> -<glyph unicode="-" horiz-adv-x="682" d="M65,440l0,181l553,0l0,-181z"/> -<glyph unicode="0" horiz-adv-x="1139" d="M85,723C85,896 103,1036 139,1142C174,1247 227,1329 298,1386C368,1443 456,1472 563,1472C642,1472 711,1456 770,1425C829,1393 878,1347 917,1288C956,1228 986,1155 1008,1070C1030,984 1041,868 1041,723C1041,551 1023,412 988,307C953,201 900,119 830,62C759,4 670,-25 563,-25C422,-25 311,26 230,127C133,249 85,448 85,723M270,723C270,482 298,322 355,243C411,163 480,123 563,123C646,123 715,163 772,243C828,323 856,483 856,723C856,964 828,1125 772,1204C715,1283 645,1323 561,1323C478,1323 412,1288 363,1218C301,1129 270,964 270,723z"/> -<glyph unicode="1" horiz-adv-x="1139" d="M763,0l-180,0l0,1147C540,1106 483,1064 413,1023C342,982 279,951 223,930l0,174C324,1151 412,1209 487,1276C562,1343 616,1409 647,1472l116,0z"/> -<glyph unicode="2" horiz-adv-x="1139" d="M1031,173l0,-173l-969,0C61,43 68,85 83,125C108,191 147,256 202,320C256,384 334,458 437,542C596,673 704,776 760,853C816,929 844,1001 844,1069C844,1140 819,1201 768,1250C717,1299 650,1323 568,1323C481,1323 412,1297 360,1245C308,1193 282,1121 281,1029l-185,19C109,1186 156,1291 239,1364C322,1436 433,1472 572,1472C713,1472 824,1433 906,1355C988,1277 1029,1180 1029,1065C1029,1006 1017,949 993,892C969,835 929,776 874,713C818,650 725,564 596,455C488,364 419,303 388,271C357,238 332,206 312,173z"/> -<glyph unicode="3" horiz-adv-x="1139" d="M86,387l180,24C287,309 322,236 372,191C421,146 482,123 553,123C638,123 709,152 768,211C826,270 855,342 855,429C855,512 828,580 774,634C720,687 651,714 568,714C534,714 492,707 441,694l20,158C473,851 483,850 490,850C567,850 636,870 697,910C758,950 789,1012 789,1095C789,1161 767,1216 722,1259C677,1302 620,1324 549,1324C479,1324 421,1302 374,1258C327,1214 297,1148 284,1060l-180,32C126,1213 176,1306 254,1373C332,1439 429,1472 545,1472C625,1472 699,1455 766,1421C833,1386 885,1339 921,1280C956,1221 974,1158 974,1091C974,1028 957,970 923,918C889,866 839,825 772,794C859,774 926,733 974,670C1022,607 1046,528 1046,433C1046,305 999,197 906,108C813,19 695,-26 552,-26C423,-26 317,12 232,89C147,166 98,265 86,387z"/> -<glyph unicode="8" horiz-adv-x="1139" d="M362,795C287,822 232,861 196,912C160,963 142,1023 142,1094C142,1201 180,1290 257,1363C334,1436 436,1472 563,1472C691,1472 794,1435 872,1361C950,1286 989,1196 989,1089C989,1021 971,962 936,912C900,861 846,822 773,795C863,766 932,718 979,653C1026,588 1049,510 1049,419C1049,294 1005,188 916,103C827,18 711,-25 566,-25C421,-25 305,18 216,104C127,189 83,296 83,424C83,519 107,599 156,664C204,728 273,772 362,795M326,1100C326,1031 348,974 393,930C438,886 496,864 567,864C636,864 693,886 738,930C782,973 804,1027 804,1090C804,1156 781,1212 736,1257C690,1302 633,1324 565,1324C496,1324 439,1302 394,1258C349,1214 326,1161 326,1100M268,423C268,372 280,322 305,274C329,226 365,189 413,163C461,136 513,123 568,123C654,123 725,151 781,206C837,261 865,332 865,417C865,504 836,575 779,632C721,689 649,717 562,717C477,717 407,689 352,633C296,577 268,507 268,423z"/> -<glyph unicode="B" horiz-adv-x="1366" d="M150,0l0,1466l550,0C812,1466 902,1451 970,1422C1037,1392 1090,1346 1129,1285C1167,1223 1186,1158 1186,1091C1186,1028 1169,969 1135,914C1101,859 1050,814 981,780C1070,754 1138,710 1186,647C1233,584 1257,510 1257,425C1257,356 1243,293 1214,234C1185,175 1149,129 1106,97C1063,65 1010,41 946,25C881,8 802,0 709,0M344,850l317,0C747,850 809,856 846,867C895,882 933,906 958,940C983,974 995,1017 995,1068C995,1117 983,1160 960,1197C937,1234 903,1259 860,1273C817,1286 742,1293 637,1293l-293,0M344,173l365,0C772,173 816,175 841,180C886,188 923,201 953,220C983,239 1008,266 1027,302C1046,337 1056,378 1056,425C1056,480 1042,527 1014,568C986,608 947,636 898,653C848,669 776,677 683,677l-339,0z"/> -<glyph unicode="C" horiz-adv-x="1479" d="M1204,514l194,-49C1357,306 1284,184 1179,101C1073,17 944,-25 791,-25C633,-25 505,7 406,72C307,136 231,229 180,351C128,473 102,604 102,744C102,897 131,1030 190,1144C248,1257 331,1344 439,1403C546,1462 665,1491 794,1491C941,1491 1064,1454 1164,1379C1264,1304 1334,1199 1373,1064l-191,-45C1148,1126 1099,1203 1034,1252C969,1301 888,1325 790,1325C677,1325 583,1298 508,1244C432,1190 379,1118 348,1027C317,936 302,842 302,745C302,620 320,512 357,419C393,326 449,256 526,210C603,164 686,141 775,141C884,141 976,172 1051,235C1126,298 1177,391 1204,514z"/> -<glyph unicode="D" horiz-adv-x="1479" d="M158,0l0,1466l505,0C777,1466 864,1459 924,1445C1008,1426 1080,1391 1139,1340C1216,1275 1274,1191 1313,1090C1351,988 1370,872 1370,741C1370,630 1357,531 1331,445C1305,359 1272,288 1231,232C1190,175 1146,131 1098,99C1049,66 991,42 923,25C854,8 776,0 687,0M352,173l313,0C762,173 838,182 893,200C948,218 991,243 1024,276C1070,322 1106,384 1132,462C1157,539 1170,633 1170,744C1170,897 1145,1015 1095,1098C1044,1180 983,1235 911,1263C859,1283 775,1293 660,1293l-308,0z"/> -<glyph unicode="I" horiz-adv-x="569" d="M191,0l0,1466l194,0l0,-1466z"/> -<glyph unicode="L" horiz-adv-x="1139" d="M150,0l0,1466l194,0l0,-1293l722,0l0,-173z"/> -<glyph unicode="P" horiz-adv-x="1366" d="M158,0l0,1466l553,0C808,1466 883,1461 934,1452C1006,1440 1066,1417 1115,1384C1164,1350 1203,1303 1233,1242C1262,1181 1277,1115 1277,1042C1277,917 1237,812 1158,726C1079,639 935,596 728,596l-376,0l0,-596M352,769l379,0C856,769 945,792 998,839C1051,886 1077,951 1077,1036C1077,1097 1062,1150 1031,1194C1000,1237 959,1266 908,1280C875,1289 815,1293 727,1293l-375,0z"/> -<glyph unicode="S" horiz-adv-x="1366" d="M92,471l183,16C284,414 304,354 336,307C367,260 416,222 483,193C550,164 625,149 708,149C782,149 847,160 904,182C961,204 1003,234 1031,273C1058,311 1072,353 1072,398C1072,444 1059,484 1032,519C1005,553 961,582 900,605C861,620 774,644 639,677C504,709 410,739 356,768C286,805 234,850 200,905C165,959 148,1020 148,1087C148,1161 169,1230 211,1295C253,1359 314,1408 395,1441C476,1474 565,1491 664,1491C773,1491 869,1474 952,1439C1035,1404 1098,1352 1143,1284C1188,1216 1212,1139 1215,1053l-186,-14C1019,1132 985,1202 928,1249C870,1296 785,1320 672,1320C555,1320 469,1299 416,1256C362,1213 335,1161 335,1100C335,1047 354,1004 392,970C429,936 527,901 685,866C842,830 950,799 1009,772C1094,733 1157,683 1198,623C1239,562 1259,493 1259,414C1259,336 1237,263 1192,194C1147,125 1083,71 1000,33C916,-6 822,-25 717,-25C584,-25 473,-6 384,33C294,72 224,130 173,208C122,285 95,373 92,471z"/> -<glyph unicode="T" horiz-adv-x="1251" d="M531,0l0,1293l-483,0l0,173l1162,0l0,-173l-485,0l0,-1293z"/> -<glyph unicode="U" horiz-adv-x="1479" d="M1120,1466l194,0l0,-847C1314,472 1297,355 1264,268C1231,181 1171,111 1084,57C997,2 882,-25 741,-25C604,-25 491,-1 404,46C317,93 254,162 217,252C180,341 161,464 161,619l0,847l194,0l0,-846C355,493 367,399 391,339C414,278 455,232 513,199C570,166 641,150 724,150C867,150 968,182 1029,247C1090,312 1120,436 1120,620z"/> -<glyph unicode="X" horiz-adv-x="1366" d="M9,0l567,764l-500,702l231,0l266,-376C628,1012 668,952 691,910C724,963 762,1019 807,1077l295,389l211,0l-515,-691l555,-775l-240,0l-369,523C723,553 702,586 680,621C647,568 624,531 610,511l-368,-511z"/> -</font> - - <rect x="7.465" y="10.627" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/> -<rect x="150.491" y="10.923" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/> -<rect x="8.479" y="129.379" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/> -<rect x="150.491" y="129.674" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/> -<rect x="8.479" y="241.805" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/> -<rect x="150.491" y="242.1" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.177"/> -<line fill="none" stroke="#000000" x1="48.716" y1="91.101" x2="48.716" y2="129.379"/> -<line fill="none" stroke="#000000" x1="88.953" y1="50.864" x2="150.491" y2="51.012"/> -<line fill="none" stroke="#000000" x1="88.953" y1="169.763" x2="150.491" y2="169.763"/> -<line fill="none" stroke="#000000" x1="190.729" y1="91.101" x2="190.729" y2="129.379"/> -<line fill="none" stroke="#000000" x1="48.716" y1="209.852" x2="48.716" y2="241.805"/> -<line fill="none" stroke="#000000" x1="88.953" y1="282.189" x2="150.491" y2="282.189"/> -<text transform="matrix(1 0 0 1 23.6948 57.3003)" font-family="'ArialMT'" font-size="18">CPU2</text> -<text transform="matrix(1 0 0 1 22.3374 174.46)" font-family="'ArialMT'" font-size="18">CPU0</text> -<text transform="matrix(1 0 0 1 169.082 55.1167)" font-family="'ArialMT'" font-size="18">CPU3</text> -<text transform="matrix(1 0 0 1 169.082 175.8271)" font-family="'ArialMT'" font-size="18">CPU1</text> -<text transform="matrix(1 0 0 1 22.6807 277.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18">PCI-X</tspan><tspan x="0" y="21.601" font-family="'ArialMT'" font-size="18">(8131)</tspan></text> -<text transform="matrix(1 0 0 1 169.082 275.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18"> SB</tspan><tspan x="0" y="21.6" font-family="'ArialMT'" font-size="18">(8111)</tspan></text> -<text transform="matrix(1 0 0 1 93.0947 63.8721)" font-family="'ArialMT'" font-size="10">LDT1</text> -<text transform="matrix(1 0 0 1 124.5088 46.7715)" font-family="'ArialMT'" font-size="10">LDT1</text> -<text transform="matrix(1 0 0 1 196.6982 102.9844)" font-family="'ArialMT'" font-size="10">LDT0</text> -<text transform="matrix(1 0 0 1 161.1953 126.0615)" font-family="'ArialMT'" font-size="10">LDT1</text> -<text transform="matrix(1 0 0 1 22.3374 126.0615)" font-family="'ArialMT'" font-size="10">LDT2</text> -<text transform="matrix(1 0 0 1 55.2783 103.5767)" font-family="'ArialMT'" font-size="10">LDT0</text> -<text transform="matrix(1 0 0 1 52.9111 221.3276)" font-family="'ArialMT'" font-size="10">LDT0</text> -<text transform="matrix(1 0 0 1 93.0947 181.6719)" font-family="'ArialMT'" font-size="10">LDT1</text> -<text transform="matrix(1 0 0 1 124.5088 166.2979)" font-family="'ArialMT'" font-size="10">LDT0</text> -<ellipse fill="#FF0606" cx="150.491" cy="51.012" rx="4.438" ry="4.563"/> -<ellipse fill="#FF0606" cx="88.953" cy="169.763" rx="4.438" ry="4.563"/> -<ellipse fill="#FF0606" cx="190.729" cy="129.379" rx="4.438" ry="4.563"/> -</svg> diff --git a/Documentation/index.html b/Documentation/index.html deleted file mode 100644 index 69f7a9b..0000000 --- a/Documentation/index.html +++ /dev/null @@ -1,26 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>coreboot Documentation</title> - </head> - <body> - -<h1>coreboot Documentation</h1> -<ul> - <li><a target="_blank" href="https://www.coreboot.org/Lesson1">Lesson 1</a></li> - <li><a href="gerrit_guidelines.md">Gerrit Guidelines</a></li> - <li><a href="timestamp.md">Timestamp</a></li> - <li>Documentation directory<a target="_blank" href=:https://review.coreboot.org/cgit/coreboot.git/tree/Documentation">listing</a></li> -</ul> - -<h1>Chipset Documentation</h1> -<ul> - <li><a target="_blank" href="Intel/index.html">Intel</a></li> - <li><a target="_blank" href="AMD-S3.txt">AMD S3</a></li> -</ul> - - -<hr> -<p>Modified: 17 June 2016</p> - </body> -</html> diff --git a/Documentation/index.md b/Documentation/index.md new file mode 100644 index 0000000..cf73558 --- /dev/null +++ b/Documentation/index.md @@ -0,0 +1,6 @@ +--- +title: "Coreboot Documentation" +date: "2016-10-01" +type: index +weight: 0 +--- diff --git a/Documentation/intel/00-index.md b/Documentation/intel/00-index.md new file mode 100644 index 0000000..ec9a8d9 --- /dev/null +++ b/Documentation/intel/00-index.md @@ -0,0 +1,11 @@ +--- +title: Intel Manual +url: intel +type: index +date: "2016-10-01" +weight: 0 +categories: + - "intel" +tags: + - "intel" +--- diff --git a/Documentation/intel/10-overview.md b/Documentation/intel/10-overview.md new file mode 100644 index 0000000..ca7b0db --- /dev/null +++ b/Documentation/intel/10-overview.md @@ -0,0 +1,187 @@ +--- +title: Overview +url: intel/overview +weight: 10 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Manual + identifier: Intel Overview + weight: 10 +--- + +## Intel® x86 Boards + +- [Galileo](../boards/galileo/index) +- [MinnowBoard MAX](http://wiki.minnowboard.org/Coreboot) + +## Intel® x86 SoCs + +- [Quark™](SoC/quark.html) + +## x86 coreboot Development + +- Get the coreboot [source](https://www.coreboot.org/Git) +- [Overall](development.html) development +- [FSP 1.1](fsp1_1.html) integration +- [SoC](SoC/soc.html) support +- [Board](Board/board.html) support + +## Payload Development + +- [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) + - [EDK II Development + Process](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Devel… + - EDK II [White + Papers](https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20Wh… + - [SourceForge to Github Quick + Start](https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to… + - UEFI [2.5 Errata + A](http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Erra… + +## Documentation + +- Intel® 64 and IA-32 Architectures [Software Developer + Manual](http://www.intel.com/content/dam/www/public/us/en/documents/manuals… +- [UEFI Specifications](http://www.uefi.org/specifications) + +## EDK-II Documentation + +- Build + [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/Bui… +- Coding Standards + [V2.1](https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_… +- DEC + [V1.25](https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC… +- DSC + [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC… +- [Driver Writer's + Guide](https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Wr…'s-Guide) +- Expression Syntax + [V1.1](https://github.com/tianocore-docs/Docs/raw/master/Specifications/Expr… +- FDF + [V1.26](https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF… +- INF + [V1.25](https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF… +- PCD + [PCD](https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_I… +- UNI [V1.2 Errata + A](https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_Fil… +- VRF + [V1.9](https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_… + +## FSP Documentation + +- Intel® Firmware Support Package External Architecture Specification + [V2.0](http://www.intel.com/content/dam/www/public/us/en/documents/technical… +- Intel® Firmware Support Package External Architecture Specification + [V1.1](http://www.intel.com/content/dam/www/public/us/en/documents/technical… +- Intel® Firmware Support Package External Architecture Specification + [V1.0](http://www.intel.com/content/dam/www/public/us/en/documents/technical… + +## Feature Documentation + +<table border="1"> +<tr bgcolor="#c0ffc0"> +<th> +Feature/Specification +</th> +<th> +Linux View/Test +</th> +<th> +EDK-II View/Test +</th> +</tr> +<tr> +<td> +<a href="https://en.wikipedia.org/wiki/E820">e820</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man1/dmesg.1.html">dmesg</a> +</td> +<td> +  +</td> +</tr> +<tr> +<td> +<a href="http://www.uefi.org/specifications">ACPI</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/precise/man1/acpidump.1.html">acpidump</a> +</td> +<td> +  +</td> +</tr> +<tr> +<td> +<a href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">parse-edid, get-edid</a> +</td> +<td> +  +</td> +</tr> +<tr> +<td> +<a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I2C</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">i2cdetect</a> +</td> +<td> +  +</td> +</tr> +<tr> +<td> +<a href="http://www.intel.com/design/archives/processors/pro/docs/242016.htm">Multiprocessor</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man1/lscpu.1.html">lscpu</a> +</td> +<td> +  +</td> +</tr> +<tr> +<td> +<a href="https://pcisig.com/specifications">PCI</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man8/lspci.8.html">lspci</a> +</td> +<td> +<a href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">pci</a> +</td> +</tr> +<tr> +<td> +<a href="https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.…">SMBIOS</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/trusty/man8/dmidecode.8.html">dmidecode</a> +</td> +<td> +<a href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">smbiosview</a> +</td> +</tr> +<tr> +<td> +<a href="http://www.usb.org/developers/docs/">USB</a> +</td> +<td> +<a href="http://manpages.ubuntu.com/manpages/xenial/man8/lsusb.8.html">lsusb</a> +</td> +<td> +  +</td> +</tr> +</table> diff --git a/Documentation/intel/20-development.md b/Documentation/intel/20-development.md new file mode 100644 index 0000000..203dafd --- /dev/null +++ b/Documentation/intel/20-development.md @@ -0,0 +1,488 @@ +--- +title: Development +url: intel/development +weight: 20 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Manual + identifier: Development + weight: 20 +--- + +## Intel® x86 coreboot/FSP Development Process + +The x86 development process for coreboot is broken into the following components: + +- coreboot [SoC](SoC/soc.html) development +- coreboot [mainboard](Board/board.html) development +- [FSP 1.1](fsp1_1.md) integration + +The development process has two main phases: + +1. Minimal coreboot; This phase is single threaded +2. Adding coreboot features + +## Minimal coreboot + +The combined steps below describe how to bring up a minimal coreboot for a system-on-a-chip (SoC) and a development board: + +## The initial coreboot steps are single threaded! The initial minimal FSP development is also single threaded. Progress can speed up by adding more developers after the minimal coreboot/FSP implementation reaches the payload. + +1. Get the necessary tools: + + - Linux: Use your package manager to install m4 bison flex and the libcurses development package. + + - Ubuntu or other Linux distribution that use apt, run: + +``` +sudo apt-get install m4 bison flex libncurses5-dev +``` + +2. Build the cross tools for i386: + + - Linux: + +``` +make crossgcc-i386 +``` + +To use multiple processors for the toolchain build (which takes a long time), use: + +``` +make crossgcc-i386 CPUS=N +``` + +where N is the number of cores to use for the build. + +3. Get something to build: + + 1. [FSP 1.1](fsp1_1.html#RequiredFiles) required files + 2. [SoC](SoC/soc.html#RequiredFiles) required files + 3. [Board](Board/board.html#RequiredFiles) required files + +4. Get result to start [booting](SoC/soc.html#Descriptor) + +5. [Early Debug](SoC/soc.html#EarlyDebug) +6. Implement and debug the [bootblock](SoC/soc.html#Bootblock) code +7. Implement and debug the call to [TempRamInit](SoC/soc.html#TempRamInit) +8. Enable the serial port + + 1. Power on, enable and configure GPIOs for the [debug serial UART](Board/board.html#SerialOutput) + 2. Add the [serial outupt](SoC/soc.html#SerialOutput) support to romstage + +9. Enable [coreboot/FSP](fsp1_1.html#corebootFspDebugging) debugging + +10. Determine the [Previous Sleep State](SoC/soc.html#PreviousSleepState) +11. Enable DRAM: + + 1. Implement the SoC [MemoryInit](SoC/soc.html#MemoryInit) Support + 2. Implement the board support to read the [Memory Timing Data](Board/board.html#SpdData) + +12. Disable the [Shadow ROM](SoC/soc.html#DisableShadowRom) + +13. Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration +14. Implement the .init routine for the [chip operations](SoC/soc.html#ChipOperations) structure which calls FSP SiliconInit +15. Start ramstage's [device tree processing](SoC/soc.html#DeviceTree) to display the PCI vendor and device IDs +16. Disable the [PCI devices](Board/board.html#DisablePciDevices) +17. Implement the [memory map](SoC/soc.html#MemoryMap) +18. coreboot should now attempt to load the payload + +## Add coreboot Features + +Most of the coreboot development gets done in this phase. Implementation tasks in this phase are easily done in parallel. + +- Payload and OS Features: + + - [ACPI Tables](SoC/soc.html#AcpiTables) + - [Legacy hardware](SoC/soc.html#LegacyHardware) support + +## Features + + <table border="1"> + <tr bgcolor="#c0ffc0"> + <th> + SoC + + </th> + <th> + Where + + </th> + <th> + Testing + + </th> + </tr> + <tr> + <td> + 8254 Programmable Interval Timer + + </td> + <td> + [Legacy hardware](SoC/soc.html#LegacyHardware) support + + </td> + <td> + [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) gets to shell + prompt + + </td> + </tr> + <tr> + <td> + 8259 Programmable Interrupt Controller + + </td> + <td> + [Legacy hardware](SoC/soc.html#LegacyHardware) support + + </td> + <td> + [CorebootPayloadPkg](SoC/quark.html#CorebootPayloadPkg) gets to shell + prompt + + </td> + </tr> + <tr> + <td> + Cache-as-RAM + + </td> + <td> + [Find](SoC/soc.html#TempRamInit) FSP binary: + [cache\_as\_ram.inc](https://review.coreboot.org/gitweb?p=coreboot.git;a=blo… + Enable: FSP 1.1 [TempRamInit](SoC/soc.html#TempRamInit) called from + [cache\_as\_ram.inc](https://review.coreboot.org/gitweb?p=coreboot.git;a=blo… + Disable: FSP 1.1 TempRamExit called from + [after\_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… + + </td> + <td> + FindFSP: POST code 0x90 + ([POST\_FSP\_TEMP\_RAM\_INIT](http://review.coreboot.org/gitweb?p=coreboot.gi…) + is displayed\ + Enable: POST code + [0x2A](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/driver… + is displayed\ + Disable: CONFIG\_DISPLAY\_MTRRS=y, MTRRs displayed after call to + TempRamExit + + </td> + </tr> + <tr> + <td> + Memory Map + + </td> + <td> + Implement a device driver for the [north + cluster](SoC/soc.html#MemoryMap) + + </td> + <td> + coreboot displays the memory map correctly during the BS\_WRITE\_TABLES + state + + </td> + </tr> + <tr> + <td> + MTRRs + + </td> + <td> + Set values: + src/drivers/intel/fsp1\_1/stack.c/[setup\_stack\_and\_mtrrs](https://review… + Load values: + src/drivers/intel/fsp1\_1/[after\_raminit.S](https://review.coreboot.org/gi… + + </td> + <td> + Set: Post code 0x91 + ([POST\_FSP\_TEMP\_RAM\_EXIT](https://review.coreboot.org/gitweb?p=coreboot.g…) + is displayed by + [after\_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… + Load: Post code 0x3C is displayed by + [after\_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… + and CONFIG\_DISPLAY\_MTRRS=y displays the correct memory regions + + </td> + </tr> + <tr> + <td> + PCI Device Support + + </td> + <td> + Implement a PCI [device driver](SoC/soc.html#DeviceDrivers) + + </td> + <td> + The device is detected by coreboot and usable by the payload + + </td> + </tr> + <tr> + <td> + Ramstage state machine + + </td> + <td> + Implement the chip and domain operations to start the [device + tree](SoC/soc.html#DeviceTree) processing + + </td> + <td> + During the BS\_DEV\_ENUMERATE state, ramstage now display the device IDs + for the PCI devices on the bus. + + </td> + </tr> + <tr> + <td> + ROM Shadow\ + 0x000E0000 - 0x000FFFFF + + </td> + <td> + Disable: src/soc/<Vendor>/<Chip + Family>/romstage/romstage.c/[soc\_after\_ram\_init + routine](SoC/soc.html#DisableShadowRom) + + </td> + <td> + Operates as RAM: Writes followed by a read to the 0x000E0000 - + 0x000FFFFF region returns the value written + + </td> + </tr> + <tr bgcolor="#c0ffc0"> + <th> + Board + + </th> + <th> + Where + + </th> + <th> + Testing + + </th> + </tr> + <tr> + <td> + Device Tree + + </td> + <td> + [List](SoC/soc.html#DeviceTree) PCI vendor and device IDs by starting + the device tree processing\ + [Disable](Board/board.html#DisablePciDevices) PCI devices\ + Enable: Implement a PCI [device driver](SoC/soc.html#DeviceDrivers) + + <td> + List: BS\_DEV\_ENUMERATE state displays PCI vendor and device IDs\ + Disable: BS\_DEV\_ENUMERATE state shows the devices as disabled\ + Enable: BS\_DEV\_ENUMERATE state shows the device as on and the device + works for the payload + + </td> + </tr> + <tr> + <td> + DRAM + + </td> + <td> + Load SPD data: + src/soc/mainboard/<Vendor>/<Board>/spd/[spd.c](Board/board.html#SpdData)\ + UPD Setup: + + - src/soc<Vendor>//<Chip + Family>/romstage/[romstage.c](SoC/soc.html#MemoryInit) + - src/mainboard/<Vendor>/<Board>/[romstage.c](Board/board.html#SpdData) + + FSP 1.1 MemoryInit called from + src/drivers/intel/fsp1\_1/[raminit.c](https://review.coreboot.org/gitweb?p=… + + </td> + <td> + Select the following Kconfig values + + - DISPLAY\_HOBS + - DISPLAY\_UPD\_DATA + + Testing successful if: + + - MemoryInit UPD values are correct + - MemoryInit returns 0 (success) and + - The the message "ERROR - coreboot's requirements not met by FSP + binary!" is not displayed + + </td> + </tr> + <tr> + <td> + Serial Port + + </td> + <td> + SoC [Support](SoC/soc.html#SerialOutput)\ + Enable: + src/soc/mainboard/<Board>/com\_init.c/[car\_mainboard\_pre\_console\_init](Board/board.html#SerialOutput) + + </td> + <td> + Debug serial output works + + </td> + </tr> + <tr bgcolor="#c0ffc0"> + <th> + Payload + + </th> + <th> + Where + + </th> + <th> + Testing + + </th> + </tr> + <tr> + <td> + ACPI Tables + + </td> + <td> + SoC [Support](SoC/soc.html#AcpiTables)\ + + </td> + <td> + Verified by payload or OS + + </td> + </tr> + <tr bgcolor="#c0ffc0"> + <th> + FSP + + </th> + <th> + Where + + </th> + <th> + Testing + + </th> + </tr> + <tr> + <td> + TempRamInit + + </td> + <td> + FSP [TempRamInit](SoC/soc.html#TempRamInit) + + </td> + <td> + FSP binary found: POST code 0x90 + ([POST\_FSP\_TEMP\_RAM\_INIT](http://review.coreboot.org/gitweb?p=coreboot.gi…) + is displayed\ + TempRamInit successful: POST code + [0x2A](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/driver… + is displayed\ + + </td> + </tr> + <tr> + <td> + MemoryInit + + </td> + <td> + [SoC](SoC/soc.html#MemoryInit) support\ + [Board](Board/board.html#SpdData) support\ + + </td> + <td> + Select the following Kconfig values + + - DISPLAY\_HOBS + - DISPLAY\_UPD\_DATA + + Testing successful if: + + - MemoryInit UPD values are correct + - MemoryInit returns 0 (success) and + - The the message "ERROR - coreboot's requirements not met by FSP + binary!" is not displayed + + </td> + </tr> + <tr> + <td> + TempRamExit + + </td> + <td> + src/drivers/intel/fsp1\_1/[after\_raminit.S](http://review.coreboot.org/git… + + </td> + <td> + Post code 0x91 + ([POST\_FSP\_TEMP\_RAM\_EXIT](https://review.coreboot.org/gitweb?p=coreboot.g…) + is displayed before calling TempRamExit by + [after\_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;…, + CONFIG\_DISPLAY\_MTRRS=y displays the correct memory regions and Post + code 0x39 is displayed by + [after\_raminit.S](https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… + + </td> + </tr> + <tr> + <td> + SiliconInit + + </td> + <td> + Implement the .init routine for the [chip + operations](SoC/soc.html#ChipOperations) structure + + </td> + <td> + During BS\_DEV\_INIT\_CHIPS state, SiliconInit gets called and returns + 0x00000000 + + </td> + </tr> + <tr> + <td> + FspNotify + + </td> + <td> + The code which calls FspNotify is located in + src/drivers/intel/fsp1\_1/[fsp\_util.c](http://review.coreboot.org/gitweb?p…. + The fsp\_notify\_boot\_state\_callback routine is called three times as + specified by the BOOT\_STATE\_INIT\_ENTRY macros below the routine. + + </td> + <td> + The FspNotify routines are called during: + + - BS\_DEV\_RESOURCES - on exit + - BS\_PAYLOAD\_LOAD - on exit + - BS\_OS\_RESUME - on entry (S3 resume) + + </td> + </tr> + </table> diff --git a/Documentation/intel/30-fsp1_1.md b/Documentation/intel/30-fsp1_1.md new file mode 100644 index 0000000..0f0fe3b --- /dev/null +++ b/Documentation/intel/30-fsp1_1.md @@ -0,0 +1,60 @@ +--- +title: FSP 1.1 +url: intel/fsp1_1 +weight: 30 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Manual + identifier: Fsp1_1 + weight: 30 +--- + +## x86 FSP 1.1 Integration + +Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC) and board support. The combined steps are listed [here](development.html). The development steps for FSP are listed below: + +1. [Required Files](#RequiredFiles) +2. Add the [FSP Binary File](#FspBinary) to the coreboot File System +3. Enable [coreboot/FSP Debugging](#corebootFspDebugging) + +FSP Documentation: + +- Intel® Firmware Support Package External Architecture Specification [V1.1](http://www.intel.com/content/dam/www/public/us/en/documents/technical… + +## Required Files + +## coreboot Required Files + +1. Create the following directories if they do not already exist: + + - src/vendorcode/intel/fsp/fsp1_1/<Chip Family> + - 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name> + +2. The following files may need to be copied from the FSP build or release into the directories above if they are not present or are out of date: + + - FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/<Chip Family>/FspUpdVpd.h + - FSP.bin: 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name>/fsp.bin + + +## Add the FSP Binary File to coreboot File System + +Add the FSP binary to the coreboot flash image using the following command: + +``` +util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b <base address> -f fsp.bin +``` + +This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the FSP code for TempRamInit may be executed in place. + +## Enable coreboot/FSP Debugging + +Set the following Kconfig values: + +- CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage +- CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit +- CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP +- CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit diff --git a/Documentation/intel/40-boards.md b/Documentation/intel/40-boards.md new file mode 100644 index 0000000..331b323 --- /dev/null +++ b/Documentation/intel/40-boards.md @@ -0,0 +1,163 @@ +--- +title: Boards +url: intel/boards +weight: 40 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Manual + identifier: Intel Boards + weight: 40 +--- + +[<figure><img src="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg" width="150" alt="Galileo Board" align="middle"><figcaption>Galileo Gen 2</figcaption></figure>](galileo/index) + +## x86 Board Development + +Board development requires System-on-a-Chip (SoC) support. The combined steps are listed [here](../development.html). The development steps for the board are listed below: + +1. [Required Files](#RequiredFiles) +2. Enable [Serial Output](#SerialOutput) +3. Load the [Memory Timing Data](#SpdData) +4. [Disable](#DisablePciDevices) the PCI devices +5. [ACPI Tables](#AcpiTables) + + +## Required Files + +Create the board directory as src/mainboard/<Vendor>/<Board>. + +The following files are required to build a new board: + +1. Kconfig.name - Defines the Kconfig value for the board +2. Kconfig + + 1. Selects the SoC for the board and specifies the SPI flash size + + 1. BOARD_ROMSIZE_KB_<Size> + 2. SOC_<Vendor>\_<Chip Family> + + 2. Declare the Kconfig values for: + + 1. MAINBOARD_DIR + 2. MAINBOARD_PART_NUMBER + 3. MAINBOARD_VENDOR + +3. devicetree.cb - Enable root bridge and serial port + + 1. The first line must be "chip soc/Intel/<soc family>"; this path is used by the generated static.c to include the chip.h header file + +4. romstage.c + + 1. Add routine mainboard_romstage_entry which calls romstage_common + +5. Configure coreboot build: + + 1. Set LOCALVERSION + 2. Select vendor for the board + 3. Select the board + 4. CBFS_SIZE = 0x00100000 + 5. Set the CPU_MICROCODE_CBFS_LEN + 6. Set the CPU_MICROCODE_CBFS_LOC + 7. Set the FSP_IMAGE_ID_STRING + 8. Set the FSP_LOC + 9. Disable GOP_SUPPORT + 10. No payload + 11. Choose the default value for all other options + +## Enable Serial Output + +Use the following steps to enable serial output: + +1. Implement the car_mainboard_pre_console_init routine in the com_init.c file: + + 1. Power on and enable the UART controller + 2. Connect the UART receive and transmit data lines to the appropriate SoC pins + +2. Add Makefile.inc + + 1. Add com_init.c to romstage + +## Memory Timing Data + +Memory timing data is located in the flash. This data is in the format of [serial presence detect](https://en.wikipedia.org/wiki/Serial_presence_detect) (SPD) data. Use the following steps to load the SPD data: + +1. Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the display of the SPD data being passed to MemoryInit +2. Create an "spd" subdirectory +3. Create an spd/spd.c file for the SPD implementation + + 1. Implement the mainboard_fill_spd_data routine + + 1. Read the SPD data either from the spd.bin file or using I2C or SMBUS + 2. Fill in the pei_data structure with SPD data for each of the DIMMs + 3. Set the DIMM channel configuration + +4. Add an .spd.hex file containing the memory timing data to the spd subdirectory + +5. Create spd/Makefile.inc + + 1. Add spd.c to romstage + 2. Add the .spd.hex file to SPD_SOURCES + +6. Edit Makefile.inc to add the spd subdirectory + +7. Edit romstage.c + + 1. Call mainboard_fill_spd_data + 2. Add mainboard_memory_init_params to copy the SPD and DRAM configuration data from the pei_data structure into the UPDs for MemoryInit + +8. Edit devicetree.cb + + 1. Include the UPD parameters for MemoryInit except for: + + - Address of SPD data + - DRAM configuration set above + +9. A working FSP [MemoryInit](../fsp1_1.html#MemoryInit) routine is required to complete debugging + +10. Debug the result until port 0x80 outputs + + 1. 0x34: - Just after entering [raminit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/driv… + 2. 0x36: - Just before displaying the [UPD parameters](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/d… for FSP MemoryInit + 3. 0x92: [POST_FSP_MEMORY_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=bl… - Just before calling FSP [MemoryInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/d… + 4. 0x37: - Just after returning from FSP [MemoryInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/d… + +11. Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called + +## Disable PCI Devices + +Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all of the devices in the system. Edit the devicetree.cb file: + +1. Edit the devicetree.cb file: + + 1. Add an entry for a PCI device.function and turn it off. The entry should look similar to: + +``` +device pci 14.0 off end +``` + + 2. Turn on the devices for: + + - Memory Controller + - Debug serial device + +2. Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices + +## ACPI Tables + +1. Edit Kconfig + + 1. Add "select HAVE_ACPI_TABLES" + +2. Add the acpi_tables.c module: + + 1. Include soc/acpi.h + 2. Add the acpi_create_fadt routine + + 1. fill in the ACPI header + 2. Call the acpi_fill_in_fadt routine + +3. Add the dsdt.asl module: diff --git a/Documentation/intel/50-soc.md b/Documentation/intel/50-soc.md new file mode 100644 index 0000000..4116749 --- /dev/null +++ b/Documentation/intel/50-soc.md @@ -0,0 +1,402 @@ +--- +title: SoC's +url: intel/soc +weight: 50 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Manual + identifier: Intel SoC + weight: 50 +--- + +[<img src="https://en.wikichip.org/w/images/7/78/intel_quark.jpg" width="100" alt="Quark™ SoC" align="middle">](quark/index) + +## x86 System on a Chip (SoC) Development + +SoC development is best done in parallel with development for a specific board. The combined steps are listed [here](../development.html). The development steps for the SoC are listed below: + +1. [FSP 1.1](../fsp1_1.html#RequiredFiles) required files +2. SoC [Required Files](#RequiredFiles) +3. [Start Booting](#Descriptor) +4. [Early Debug](#EarlyDebug) +5. [Bootblock](#Bootblock) +6. [TempRamInit](#TempRamInit) +7. [Romstage](#Romstage) + + 1. Enable [Serial Output"](#SerialOutput) + 2. Get the [Previous Sleep State](#PreviousSleepState) + 3. Add the [MemoryInit](#MemoryInit) Support + 4. Disable the [Shadow ROM](#DisableShadowRom) + +8. [Ramstage](#Ramstage) + + 1. [Start Device Tree Processing](#DeviceTree) + 2. Set up the [Memory Map"](#MemoryMap) + +9. [ACPI Tables](#AcpiTables) + +10. [Legacy Hardware](#LegacyHardware) + + +## Required Files + +Create the directory as src/soc/<Vendor>/<Chip Family>. + +The following files are required to build a new SoC: + +- Include files + + - include/soc/pei_data.h + - include/soc/pm.h + +- Kconfig - Defines the Kconfig value for the SoC and selects the tool chains for the various stages: + + - select ARCH_BOOTBLOCK_<Tool Chain> + - select ARCH_RAMSTAGE_<Tool Chain> + - select ARCH_ROMSTAGE_<Tool Chain> + - select ARCH_VERSTAGE_<Tool Chain> + +- Makefile.inc - Specify the include paths +- memmap.c - Top of usable RAM + + +## Start Booting + +Some SoC parts require additional firmware components in the flash. This section describes how to add those pieces. + +### Intel Firmware Descriptor + +The Intel Firmware Descriptor (IFD) is located at the base of the flash part. The following command overwrites the base of the flash image with the Intel Firmware Descriptor: + +``` +dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1 +``` + +### Management Engine Binary + +Some SoC parts contain and require that the Management Engine (ME) be running before it is possible to bring the x86 processor out of reset. A binary file containing the management engine code must be added to the firmware using the ifdtool. The following commands add this binary blob: + +``` +util/ifdtool/ifdtool -i ME:me.bin build/coreboot.rom +mv build/coreboot.rom.new build/coreboot.rom +``` + +### Early Debug + +Early debugging between the reset vector and the time the serial port is enabled is most easily done by writing values to port 0x80. + +### Success + +When the reset vector is successfully invoked, port 0x80 will output the following value: + +- 0x01: [POST_RESET_VECTOR_CORRECT](http://review.coreboot.org/gitweb?p=coreboot.git… - Bootblock successfully executed the [reset vector](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x… and entered the 16-bit code at [_start](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x… + +## Bootblock + +Implement the bootblock using the following steps: + +1. Create the directory as src/soc/<Vendor>/<Chip Family>/bootblock +2. Add the timestamp.inc file which initializes the floating point registers and saves the initial timestamp. +3. Add the bootblock.c file which: + + 1. Enables memory-mapped PCI config access + 2. Updates the microcode by calling intel_update_microcode_from_cbfs + 3. Enable ROM caching + +4. Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file + + 1. Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file + 2. Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file + +5. Edit the src/soc/<Vendor>/<Chip Family>/Makefile.inc file + + 1. Add the bootblock subdirectory + +6. Edit the src/soc/<Vendor>/<Chip Family>/memmap.c file + + 1. Add the fsp/memmap.h include file + 2. Add the mmap_region_granularity routine + +7. Add the necessary .h files to define the necessary values and structures + +8. When successful port 0x80 will output the following values: + + 1. 0x01: [POST_RESET_VECTOR_CORRECT](http://review.coreboot.org/gitweb?p=coreboot.git… - Bootblock successfully executed the [reset vector](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x… and entered the 16-bit code at [_start](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x… + 2. 0x10: [POST_ENTER_PROTECTED_MODE](http://review.coreboot.org/gitweb?p=coreboot.git… - Bootblock executing in [32-bit mode](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86… + 3. 0x10 - Verstage/romstage reached 32-bit mode + +**Build Note:** The following files are included into the default bootblock image: + +- [src/arch/x86/bootblock_romcc.S](http://review.coreboot.org/gitweb?p=coreboo… added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git… and includes the following files: + + - [src/arch/x86/prologue.inc](http://review.coreboot.org/gitweb?p=coreboot.git… + - [src/cpu/x86/16bit/reset16.inc](http://review.coreboot.org/gitweb?p=coreboot… + - [src/cpu/x86/16bit/entry16.inc](http://review.coreboot.org/gitweb?p=coreboot… + - [src/cpu/x86/32bit/entry32.inc](http://review.coreboot.org/gitweb?p=coreboot… + - The code in [src/arch/x86/bootblock_romcc.S](http://review.coreboot.org/gitweb?p=coreboo… includes src/soc/<Vendor>/<Chip Family>/bootblock/timestamp.inc using the CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above + - [src/cpu/x86/sse_enable.inc](http://review.coreboot.org/gitweb?p=coreboot.gi… + - The code in [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git… invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc: + + - [src/arch/x86/include/arch/bootblock_romcc.h](http://review.coreboot.org/git… + - [src/cpu/x86/lapic/boot_cpu.c](http://review.coreboot.org/gitweb?p=coreboot.… + - The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in src/soc/<Vendor>/<Chip Family>/bootblock/bootblock.c + +- [src/arch/x86/id.S](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git… +- [src/cpu/intel/fit/fit.S](http://review.coreboot.org/gitweb?p=coreboot.git;a… added by [src/cpu/intel/fit/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboo… +- [src/arch/x86/walkcbfs.S](http://review.coreboot.org/gitweb?p=coreboot.git;a… added by [src/arch/x86/Makefile.inc](http://review.coreboot.org/gitweb?p=coreboot.git… + +## TempRamInit + +Enable the call to TempRamInit in two stages: + +1. Finding the FSP binary in the read-only CBFS region +2. Call TempRamInit + +### Find FSP Binary + +Use the following steps to locate the FSP binary: + +1. Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file + + 1. Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of [src/drivers/intel/fsp1_1/cache_as_ram.inc](http://review.coreboot.org/gitwe… + 2. Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common specifically building [util.c](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/i… + +2. Debug the result until port 0x80 outputs + + 1. 0x90: [POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=… - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/… + 2. Alternating 0xba and 0x01 - The FSP image was not found + +3. Add the [FSP binary file](../fsp1_1.html#FspBinary) to the flash image + +4. Set the following Kconfig values: + + - CONFIG_FSP_LOC to the FSP base address specified in the previous step + - CONFIG_FSP_IMAGE_ID_STRING + +5. Debug the result until port 0x80 outputs + + 1. 0x90: [POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=… - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/… + 2. Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found + +### Calling TempRamInit + +Use the following steps to debug the call to TempRamInit: + +1. Add the CPU microcode update file + + 1. Add the microcode file with the following command + +``` +util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b <base address> -f cpu_microcode_blob.bin +``` + + 2. Set the Kconfig values + + - CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step + - CONFIG_CPU_MICROCODE_CBFS_LEN + +2. Debug the result until port 0x80 outputs + + 1. 0x90: [POST_FSP_TEMP_RAM_INIT](http://review.coreboot.org/gitweb?p=coreboot.git;a=… - Just before calling [TempRamInit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/… + 2. 0x2A - Just before calling [cache_as_ram_main](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;… which is the start of the verstage code which may be part of romstage + +## Romstage + +### Serial Output + +The following steps add the serial output support for romstage: + +1. Create the romstage subdirectory +2. Add romstage/romstage.c + + 1. Program the necessary base addresses + 2. Disable the TCO + +3. Add romstage/Makefile.inc + + 1. Add romstage.c to romstage + +4. Add gpio configuration support if necessary + +5. Add the necessary .h files to support the build +6. Update Makefile.inc + + 1. Add the romstage subdirectory + 2. Add the gpio configuration support file to romstage + +7. Set the necessary Kconfig values to enable serial output: + + - CONFIG_DRIVERS_UART_<driver>=y + - CONFIG_CONSOLE_SERIAL=y + - CONFIG_UART_FOR_CONSOLE=<port> + - CONFIG_CONSOLE_SERIAL_115200=y + +### Determine Previous Sleep State + +The following steps implement the code to get the previous sleep state: + +1. Implement the fill_power_state routine which determines the previous sleep state +2. Debug the result until port 0x80 outputs + + 1. 0x32: - Just after entering [romstage_common](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=… + 2. 0x33 - Just after calling [soc_pre_ram_init](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f… + 3. 0x34: - Just after entering [raminit](http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/driv… + +### MemoryInit Support + +The following steps implement the code to support the FSP MemoryInit call: + +1. Add the chip.h header file to define the UPD values which get passed to MemoryInit. Skip the values containing SPD addresses and DRAM configuration data which is determined by the board. + + **Build Note**: The src/mainboard/<Vendor>/<Board>/devicetree.cb file specifies the default values for these parameters. The build process creates the static.c module which contains the config data structure containing these values. + +2. Edit romstage/romstage.c + + 1. Implement the romstage/romstage.c/soc_memory_init_params routine to copy the values from the config structure into the UPD structure + 2. Implement the soc_display_memory_init_params routine to display the updated UPD parameters by calling fsp_display_upd_value + +### Disable Shadow ROM + +A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff. This shadow needs to be disabled to allow RAM to properly respond to this address range. + +1. Edit romstage/romstage.c and add the soc_after_ram_init routine + +## Ramstage + +### Start Device Tree Processing + +The src/mainboard/<Vendor>/<Board>/devicetree.cb file drives the execution during ramstage. This file is processed by the util/sconfig utility to generate build/mainboard/<Vendor>/<Board>/static.c. The various state routines in src/lib/[hardwaremain.c](http://review.coreboot.org/gitweb?p=coreboot.git;a… call dev_* routines which use the tables in static.c to locate operation tables associated with the various chips and devices. After location the operation tables, the state routines call one or more functions depending upon the state of the state machine. + +#### Chip Operations + +Kick-starting the ramstage state machine requires creating the operation table for the chip listed in devicetree.cb: + +1. Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c: + + 1. This chip's operation table has the name soc_<SoC Vendor>\_<SoC Family>\_ops which is derived from the chip path specified in the devicetree.cb file. + 2. Use the CHIP_NAME macro to specify the name for the chip + 3. For FSP 1.1, specify a .init routine which calls intel_silicon_init + +2. Edit src/soc/<SoC Vendor>/<SoC Family>/Makefile.inc and add chip.c to ramstage + +### Domain Operations + +coreboot uses the domain operation table to initiate operations on all of the devices in the domain. By default coreboot enables all PCI devices which it finds. Listing a device in devicetree.cb gives the board vendor control over the device state. Non-PCI devices may also be listed under PCI device such as the LPC bus or SMbus devices. + +1. Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c: + + 1. The domain operation table is typically placed in src/soc/<SoC Vendor>/<SoC Family>/chip.c. The table typically looks like the following: + +``` +static struct device_operations pci_domain_ops = { + .read_resources = pci_domain_read_resources, + .set_resources = pci_domain_set_resources, + .scan_bus = pci_domain_scan_bus, + .ops_pci_bus = pci_bus_default_ops, +}; +``` + + 2. Create a .enable_dev entry in the chip operations table which points to a routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN. + +``` +if (dev->path.type == DEVICE_PATH_DOMAIN) { + dev->ops = &pci_domain_ops; +} +``` + + 3. During the BS_DEV_ENUMERATE state, ramstage now display the device IDs for the PCI devices on the bus. + +2. Set CONFIG_DEBUG_BOOT_STATE=y in the .config file + +3. Debug the result until the PCI vendor and device IDs are displayed during the BS_DEV_ENUMERATE state. + +## PCI Device Drivers + +PCI device drivers consist of a ".c" file which contains a "pci_driver" data structure at the end of the file with the attribute tag "\__pci_driver". This attribute tag places an entry into a link time table listing the various coreboot device drivers. + +Specify the following fields in the table: + +1. .vendor - PCI vendor ID value of the device +2. .device - PCI device ID value of the device or\ .devices - Address of a zero terminated array of PCI device IDs +3. .ops - Operations table for the device. This is the address of a "static struct device_operations" data structure specifying the routines to execute during the different states and sub-states of ramstage's processing. +4. Turn on the device in mainboard/<Vendor>/<Board>/devicetree.cb +5. Debug until the device is on and properly configured in coreboot and usable by the payload + +### Subsystem IDs + +PCI subsystem IDs are assigned during the BS_DEV_ENABLE state. The device driver may use the common mechanism to assign subsystem IDs by adding the ".ops_pci" to the pci_driver data structure. This field points to a "struct pci_operations" that specifies a routine to set the subsystem IDs for the device. The routine might look something like this: + +``` +static void pci_set_subsystem(device_t dev, unsigned vendor, unsigned device) +{ + if (!vendor || !device) { + vendor = pci_read_config32(dev, PCI_VENDOR_ID); + device = vendor >> 16; + } + printk(BIOS_SPEW, + "PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n", + 0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn), + vendor & 0xffff, device); + pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID, + ((device & 0xffff) << 16) | (vendor & 0xffff)); +} +``` + +## Set up the Memory Map + +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 device_t data structure by src/device/device_util.c/[new_resource](http://review.coreboot.org/gitweb?p…. + +During the BS_WRITE_TABLES state, coreboot collects these resources and places them into a data structure identified by LB_MEM_TABLE. + +Edit the device driver file: + +1. Implement a read_resources routine which calls macros defined in src/include/device/[device.h](http://review.coreboot.org/gitweb?p=coreboot.… like: + + - ram_resource + - reserved_ram_resource + - bad_ram_resource + - uma_resource + - mmio_resource + +Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state. + +## ACPI Tables + +One of the payloads that needs ACPI tables is the EDK2 [CorebootPayloadPkg](quark.html#CorebootPayloadPkg). + +### FADT + +The EDK2 module CorebootModulePkg/Library/CbParseLib/[CbParseLib.c](https://github.com/tian… requires that the FADT contains the values in the table below. These values are placed into a HOB identified by [gUefiAcpiBoardInfoGuid](https://github.com/tianocore/edk2/blob/master/Coreb… by routine CorebootModulePkg/CbSupportPei/CbSupportPei/[CbPeiEntryPoint](https://githu…. + +| Coreboot Field | EDK2 Field | gUefiAcpiBoardInfoGuid | Use | [ACPI Spec.](http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf) Section | +|---|---|---|---|---| +| gpe0_blk\ gpe0_blk_len | Gpe0Blk\ Gpe0BlkLen | [PmGpeEnBase](https://github.com/tianocore/edk2/blob/master/CorebootModulePk… | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/… | 4.8.4.1 | +| pm1a_cnt_blk | Pm1aCntBlk | PmCtrlRegBase | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/… \ [Suspend](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/L… | 4.8.3.2.1 | +| pm1a_evt_blk | Pm1aEvtBlk | PmEvtBase | [Shutdown](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/… | 4.8.3.1.1 | +| pm_tmr_blk | PmTmrBlk | PmTimerRegBase | [Timer](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Lib… | 4.8.3.3 | +| reset_reg. | ResetReg.Address | ResetRegAddress | [Cold](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Libr… and [Warm](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Libr… resets | 4.3.3.6 | +| reset_value | ResetValue | ResetValue | [Cold](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Libr… and [Warm](https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Libr… resets | 4.8.3.6 | + + The EDK2 data structure is defined in MdeModulePkg/Include/IndustryStandard/[Acpi61.h](https://github.com/tianoco… The coreboot data structure is defined in src/arch/x86/include/arch/[acpi.h](http://review.coreboot.org/gitweb?p=core… + +1. Select [HAVE_ACPI_TABLES](../Board/board.html#AcpiTables) in the board's Kconfig file +2. Create a acpi.c module: + + 1. Add the acpi_fill_in_fadt routine and initialize the values above + +## Legacy Hardware + +One of the payloads that needs legacy hardare is the EDK2 [CorebootPayloadPkg](quark.html#CorebootPayloadPkg). + +Peripheral Use 8259 Interrupt Vector IDT Base Offset Interrupt Handler + +[8254](http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf) Programmable Interval Timer EDK2: PcAtChipsetPkg/8254TimerDxe/[Timer.c](https://github.com/tianocore/edk2/blo… 0 0x340 [TimerInterruptHandler](https://github.com/tianocore/edk2/blob/master/PcAtCh… + +[8259](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwibxYKU3ZDLAhVOzWMKHfuqB40QFggcMAA&url=http%3A%2F%2Fbochs.sourceforge.net%2Ftechspec%2Fintel-8259a-pic.pdf.gz&usg=AFQjCNF1NT0OQ6ys1Pn6Iv9sv6cKRzZbGg&sig2=HfBszp9xTVO_fajjPWCsJw) Programmable Interrupt Controller EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/[8259.c](https://github.com/tiano… Master interrupts: 0, 2 - 7\ Master: 0x340, 0x350 - 0x378\<br> +Slave interrupts: 8 - 15\ Slave: 0x380 - 0x3b8\ + +Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15 . Interrupt descriptors are 8 bytes each diff --git a/Documentation/intel/boards/galileo/00-index.md b/Documentation/intel/boards/galileo/00-index.md new file mode 100644 index 0000000..0eb8717 --- /dev/null +++ b/Documentation/intel/boards/galileo/00-index.md @@ -0,0 +1,93 @@ +--- +title: Galileo Board +url: intel/boards/galileo/index +weight: 00 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel Boards + identifier: Galileo + weight: 00 +--- + +![Galileo Gen2](http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg "Galileo Board Gen2") + +## Intel® Galileo Development Board + +The Intel® Galileo Gen 2 mainboard code was developed along with the Intel® [Quark™](../SoC/quark.html) + +- [Overall](../development.html) +- [SoC](../SoC/soc.html) support +- [FSP 1.1](../fsp1_1.html) integration +- [Board](board.html) support +- [Implementation Checklist](checklist) + +## Galileo Board Documentation + +- Common Components + + - A/D: Texas Instruments [ADC108S102](http://www.ti.com/lit/ds/symlink/adc108s102.pdf) + - Analog Switch: Texas Instruments [TS5A23159](http://www.ti.com/lit/ds/symlink/ts5a23159.pdf) + - Ethernet (10/100 MB/S): Texas Instruments [DP83848](http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf) + - Load Switch: Texas Instruments [TPS22920x](http://www.ti.com/lit/ds/symlink/tps22920.pdf) + - Memory (256 MiB): Micron [MT41K128M8](https://www.micron.com/~/media/Documents/Products/Data%20Sheet/… + - SoC: Intel® Quark™ [X-1000](../SoC/quark.html) + - Serial EEPROM (1 KiB): ON Semiconductor® [CAT24C08](http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF) + - SPI Flash (8 MiB): Winbond™ [W25Q64FV](http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.p… + - Step Down Converter: Texas Instruments [TPS62130](http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf) + - Step Down Converter: Texas Instruments [TPS652510](http://www.ti.com/lit/ug/slvu570/slvu570.pdf) + - Termination Regulator: Texas Instruments [TPS51200](http://www.ti.com/lit/ds/symlink/tps51200.pdf) + +- Make a bootable [micro SD card](https://software.intel.com/en-us/get-started-galileo-linux-step1) + +### Galileo Gen 2 Board Documentation + +- [Block Diagram](http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg) +- [Getting Started](https://software.intel.com/en-us/iot/library/galileo-getting-start… +- [Overview](http://www.intel.com/content/www/us/en/embedded/products/galileo/… +- [Port Diagram](http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg) +- [Product Brief](http://download.intel.com/support/galileo/sb/intelgalileogen2prodbri… +- [Schematic](http://www.intel.com/content/dam/www/public/us/en/documents/guid… +- [User Guide](http://download.intel.com/support/galileo/sb/galileo_boarduserguide_… +- Components + + - A/D: Texas Instruments [ADC108S102](http://www.ti.com/lit/ds/symlink/adc108s102.pdf) + - I2C 16-channel, 12-bit PWM: NXP Semiconductors [PCA9685](http://cache.nxp.com/documents/data_sheet/PCA9685.pdf) + - I2C I/O Ports: NXP Semiconductors [PCAL9535A](http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf) + - Octal Buffer/Driver: Texas Instruments [SN74LV541AT](http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf) + - Quadruple Bus Buffer: Texas Instruments [SN74LV125A](http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf) + - Quadruple Bus Buffer with 3-State Outputs: Texas Instruments [SN74LVC126A](http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf) + - Serial EEPROM (1 KiB): ON Semiconductor® [CAT24C08](http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF) + - Single 2-input multiplexer: NXP Semiconductors [74LVC1G157](http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf) + - Step Down Converter: Texas Instruments [TPS62130](http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf) + +### Galileo Gen 1 Board Documentation + +- [Datasheet](http://www.intel.com/content/dam/www/public/us/en/documents/data… +- [Schematic](http://www.intel.com/content/dam/www/public/us/en/documents/guid… +- Components + + - A/D: Analog Devices [AD7298](http://www.analog.com/media/en/technical-documentation/data-sheets/… + - Analog Switch, 2 channel: Texas Instruments [TS5A23159](http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf) + - EEPROM & GPIO: Cypress [CY8C9540A](http://www.cypress.com/file/37971/download) + - Power Distribution Switch: Texas Instruments [TPS2051BDBVR](http://www.ti.com/lit/ds/symlink/tps2044b.pdf) + - RS232 Converter: Texas Instruments [MAX3232](http://www.ti.com/lit/ds/symlink/max3232.pdf) + - Voltage-Level Translator: Texas Instruments[TXS0108E](http://www.ti.com/lit/ds/symlink/txs0108e.pdf) + +## Debug Tools + +- Flash Programmer: + + - Dediprog [SF100](http://www.dediprog.com/pd/spi-flash-solution/SF100) ISP IC Programmer + +- JTAG Connector: [Olimex ARM-JTAG-20-10](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&… +- JTAG Debugger: + + - Olimex LTD [ARM-USB-OCD-H](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&e… + - Tincan Tools [Flyswatter2](https://www.tincantools.com/wiki/Flyswatter2) + +- [Hardware Setup and Software Installation](http://download.intel.com/support/processors/quark/sb/sourced… +- USB Serial cable: FTDI [TTL-232R-3V3](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&es… diff --git a/Documentation/intel/boards/galileo/10-checklist.md b/Documentation/intel/boards/galileo/10-checklist.md new file mode 100644 index 0000000..3622df5 --- /dev/null +++ b/Documentation/intel/boards/galileo/10-checklist.md @@ -0,0 +1,1361 @@ +--- +title: Galileo Checklist +url: intel/boards/galileo/checklist +weight: 10 +categories: + - intel +tags: + - intel +menu: + main: + parent: Intel Boards + identifier: Galileo Checklist + weight: 10 +--- + +# Galileo Implementation Status + +<table> + <tr> + <td colspan="2"> + **Legend** + + </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: 66% 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="#ffffc0"> + <td> + Optional + + </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: 55% 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="#ffffc0"> + <td> + Optional + + </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> diff --git a/Documentation/intel/soc/quark/00-index.md b/Documentation/intel/soc/quark/00-index.md new file mode 100644 index 0000000..0f53238 --- /dev/null +++ b/Documentation/intel/soc/quark/00-index.md @@ -0,0 +1,144 @@ +--- +title: Quark SoC +url: intel/soc/quark/index +weight: 00 +categories: + - "intel" +tags: + - "intel" +menu: + main: + parent: Intel SoC + identifier: Quark + weight: 00 +--- + +![Quark Block Diagram](http://www.intel.com/content/dam/www/public/us/en/images/embedded/… + +## Intel® Quark™ SoC + +The Quark™ SoC code was developed using the [Galileo Gen2](../Board/galileo.html) board: + + - [Overall](../development.html) development + - [SoC](soc.html) support + - [FSP 1.1](../fsp1_1.html) integration + - [Board](../Board/board.html) support + - [Quark™ FSP](#QuarkFsp) + - [CorebootPayloadPkg](#CorebootPayloadPkg) + +## Quark™ Documentation + +- [Block Diagram](http://www.intel.com/content/dam/www/public/us/en/images/embedded/… +- [Specifications](http://www.intel.com/content/www/us/en/embedded/products/qu…: + + - [X1000](http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-… - [Documentation](http://www.intel.com/content/www/us/en/search.html?keyword=X…: + + - [Datasheet](http://www.intel.com/content/dam/www/public/us/en/documents/data… + - [Developer's Manual](http://www.intel.com/content/dam/support/us/en/documents/processors… + - [Product Brief](http://www.intel.com/content/dam/www/public/us/en/documents/product-… + +- [More documentation](../index.html#Documentation) + +## Quark™ EDK2 CorebootPayloadPkg + +Build Instructions: + +1. Set up [build environment](#BuildEnvironment) +2. Linux (assumes GCC48): + +``` + build -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc -a IA32 \ + -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 \ + -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL \ + -DMAX_LOGICAL_PROCESSORS=1 + ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd +``` + +3. Windows (assumes Visual Studio 2015): + +``` + build -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc -a IA32 -t VS2015x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL -DMAX_LOGICAL_PROCESSORS=1 + dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd +``` + +4. In the .config for coreboot, set the following Kconfig values: + + - CONFIG_PAYLOAD_ELF=y + - CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd" + +5. Build coreboot + +6. Copy the image build/coreboot.rom into flash + +## Quark™ EDK2 Build Environment + +Use the following steps to setup a build environment: + +1. Get the EDK2 sources: + + 1. EDK2: git clone <https://github.com/tianocore/edk2.git> + 2. EDK2-non-osi: git clone <https://github.com/tianocore/edk2-non-osi.git> + 3. Win32 BaseTools: git clone <https://github.com/tianocore/edk2-BaseTools-win32.git> + +2. Set up a build window: + + - Linux: + +``` +export WORKSPACE=$PWD +export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi" +cd edk2 +export WORKSPACE=$PWD +. edksetup.sh +``` + + - Windows: + +``` +set WORKSPACE=%CD% +set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi +set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32 +cd edk2 +edksetup.bat +``` + +## Quark™ FSP + +Getting the Quark FSP source: + +1. Set up an EDK-II [Build Environment](#BuildEnvironment) +2. cd edk2 +3. mkdir QuarkFspPkg +4. cd QuarkFspPkg +5. Use git to clone [QuarkFspPkg](https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp) into the QuarkFpsPkg directory (.) + +Building QuarkFspPkg: + +- Linux: QuarkFspPkg/BuildFsp.sh -d32 +- Windows: QuarkFspPkg/BuildFsp.bat -d32 + +## Quark™ EDK2 BIOS + +Build Instructions: + +1. Set up [build environment](#BuildEnvironment) +2. Build the image: + + - Linux: + +``` +build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 +ls Build/Quark/DEBUG_GCC48/FV/Quark.fd +``` + + - Windows: + +``` +build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t VS2012x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 +dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd +``` + +Documentation: + +- [EDK II firmware for Intel® Quark™ SoC X1000 based platforms](https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg) +- Intel® Quark™ SoC X1000 [UEFI Firmware Writer's Guide](http://www.intel.com/content/dam/www/public/us/en/documents/guides/q… diff --git a/Documentation/mainboard_io_trap_handler_sample.c b/Documentation/mainboard_io_trap_handler_sample.c deleted file mode 100644 index f440f8d..0000000 --- a/Documentation/mainboard_io_trap_handler_sample.c +++ /dev/null @@ -1,51 +0,0 @@ -/* - * This file is part of the coreboot project. - * - * Copyright (C) 2008-2009 coresystems GmbH - * Copyright 2013 Google Inc. - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - */ - -#include <arch/io.h> -#include <console/console.h> -#include <cpu/x86/smm.h> -#include <soc/pm.h> -#include <soc/smm.h> -#include <elog.h> -#include <ec/google/chromeec/ec.h> -#include <soc/gpio.h> -#include <soc/iomap.h> -#include <soc/nvs.h> -#include <soc/pm.h> -#include <soc/smm.h> -#include "ec.h" -#include "gpio.h" - -int mainboard_io_trap_handler(int smif) -{ - switch (smif) { - case 0x99: - printk(BIOS_DEBUG, "Sample\n"); - smm_get_gnvs()->smif = 0; - break; - default: - return 0; - } - - /* On success, the IO Trap Handler returns 0 - * On failure, the IO Trap Handler returns a value != 0 - * - * For now, we force the return value to 0 and log all traps to - * see what's going on. - */ - //smm_get_gnvs()->smif = 0; - return 1; -} diff --git a/Documentation/submodules.txt b/Documentation/submodules.txt deleted file mode 100644 index 631e3513..0000000 --- a/Documentation/submodules.txt +++ /dev/null @@ -1,46 +0,0 @@ -Use of git submodules in coreboot -================================= -coreboot uses git submodules to keep certain parts of the tree separate, -with two major use cases: - -First, we use a vendor tool by NVIDIA for systems based on their SoC -and since they publish it through git, we can just import it into our -tree using submodules. - -Second, lots of boards these days require binaries and we want to keep -them separate from coreboot proper to clearly delineate shiny Open Source -from ugly blobs. -Since we don't want to impose blobs on users who really don't need them, -that repository is only downloaded and checked out on explicit request. - -Handling submodules -------------------- -For the most part, submodules should be automatically checked out on the -first execution of the coreboot Makefile. - -To manually fetch all repositories (eg. when you want to prepare the tree -for archiving, or to use it without network access), run - - $ git submodule update --init --checkout - -This also checks out the binaries below `3rdparty/` - -Mirroring coreboot ------------------- -When running a coreboot mirror to checkout from, for full operation, you -should also mirror the blobs and nvidia-cbootimage repository, and place -them in the same directory as the coreboot repository mirror. - -That is, when residing in coreboot's repository, `cd ../blobs.git` -should move you to the blobs repository. - -With that, no matter what the URL of your coreboot repository is, the -git client (of a sufficiently new version) is able to pick up the other -repositories transparently. - -Minimum requirements --------------------- -git needs to be able to handle relative paths to submodule repositories, -and it needs to know about non-automatic submodules. - -For these features, we require git version 1.7.6.1 or newer. diff --git a/Documentation/timestamp.md b/Documentation/timestamp.md deleted file mode 100644 index 3a4c73b..0000000 --- a/Documentation/timestamp.md +++ /dev/null @@ -1,200 +0,0 @@ -Table of Contents -================= -Introduction - Transition from cache to cbmem - -Data structures used - cache_state - table - entries - -Function APIs - timestamp_init - timestamp_add - timestamp_add_now - timestamp_sync - -Use / Test Cases - Case 1: Timestamp Region Exists - Case 2: No timestamp region, fresh boot, cbmem_initialize called after - timestamp_init - Case 3: No timestamp region, fresh boot, cbmem_initialize called before - timestamp_init - Case 4: No timestamp region, resume, cbmem_initialize called after - timestamp_init - Case 5: No timestamp region, resume, cbmem_initialize called before - timestamp_init - - -Introduction -============ -The aim of the timestamp library is to make it easier for different boards -to save timestamps in cbmem / stash (until cbmem is brought up) by -providing a simple API to initialize, add and sync timestamps. In order -to make the timestamps persistent and accessible from the kernel, we -need to ensure that all the saved timestamps end up in cbmem under -the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available, -the timestamps can be saved to a SoC-defined \_timestamp region or in a -local stage-specific stash. The work of identifying the right location for -storing timestamps is done by the library and is not exposed to the user. - -Working of timestamp library from a user perspective can be outlined in -the following steps: -1. Initialize the base time and reset cbmem timestamp area -2. Start adding timestamps - -Behind the scenes, the timestamp library takes care of: -1. Identifying the correct location for storing timestamps (cbmem or timestamp - region or local stash). -2. Once cbmem is up, ensure that all timestamps are synced from timestamp - region or local stash into the cbmem area. -3. Add a new cbmem timestamp area based on whether a reset of the cbmem - timestamp region is required or not. - -Transition from cache to cbmem ------------------------------- -To move timestamps from the cache to cbmem (and initialize the cbmem area in -the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot. - -When cbmem is initialized, the hook is called, which creates the area, -copies all timestamps to cbmem and disables the cache. - -After such a transition, timestamp_init() must not be run again. - - -Data structures used -==================== -The main structure that maintains information about the timestamp cache is: -struct __attribute__((__packed__)) timestamp_cache { - uint16_t cache_state; - struct timestamp_table table; - struct timestamp_entry entries[MAX_TIMESTAMP_CACHE]; -}; - -cache_state ------------ -The state of the cache is maintained by cache_state attribute which can -be any one of the following: - -enum { - TIMESTAMP_CACHE_UNINITIALIZED = 0, - TIMESTAMP_CACHE_INITIALIZED, - TIMESTAMP_CACHE_NOT_NEEDED, -}; - -By default, if the cache is stored in local stash (bss area), then -it will be reset to uninitialized state. However, if the cache is -stored in timestamp region, then it might have garbage in any of the -attributes. Thus, if the timestamp region is being used by any board, it is -initialized to default values by the library. - -Once the cache is initialized, its state is set to -CACHE_INITIALIZED. Henceforth, the calls to cache i.e. timestamp_add -know that the state reflected is valid and timestamps can be directly -saved in the cache. - -Once the cbmem area is up (i.e. call to timestamp_sync_cache_to_cbmem), -we do not need to store the timestamps in local stash / timestamp area -anymore. Thus, the cache state is set to CACHE_NOT_NEEDED, which allows -timestamp_add to store all timestamps directly into the cbmem area. - - -table ------ -This field is represented by a structure which provides overall -information about the entries in the timestamp area: - -struct timestamp_table { - uint64_t base_time; - uint32_t max_entries; - uint32_t num_entries; - struct timestamp_entry entries[0]; /* Variable number of entries */ -} __attribute__((packed)); - -It indicates the base time for all timestamp entries, maximum number -of entries that can be stored, total number of entries that currently -exist and an entry structure to hold variable number of entries. - - -entries -------- -This field holds the details of each timestamp entry, upto a maximum -of MAX_TIMESTAMP_CACHE which is defined as 16 entries. Each entry is -defined by: - -struct timestamp_entry { - uint32_t entry_id; - uint64_t entry_stamp; -} __attribute__((packed)); - -entry_id holds the timestamp id corresponding to this entry and -entry_stamp holds the actual timestamp. - - -For timestamps stored in the cbmem area, a timestamp_table is allocated -with space for MAX_TIMESTAMPS equal to 30. Thus, the cbmem area holds -base_time, max_entries (which is 30), current number of entries and the -actual entries represented by timestamp_entry. - - -Function APIs -============= - -timestamp_init --------------- -This function initializes the timestamp cache and should be run as early -as possible. On platforms with SRAM, this might mean in bootblock, on -x86 with its CAR backed memory in romstage, this means romstage before -memory init. - -timestamp_add -------------- -This function accepts from user a timestamp id and time to record in the -timestamp table. It stores the entry in the appropriate table in cbmem -or _timestamp region or local stash. - - -timestamp_add_now ------------------ -This function calls timestamp_add with user-provided id and current time. - - -Use / Test Cases -================ - -The following cases have been considered while designing the timestamp -library. It is important to ensure that any changes made to this library satisfy -each of the following use cases: - -Case 1: Timestamp Region Exists (Fresh Boot / Resume) ------------------------------------------------------ - -In this case, the library needs to call timestamp_init as early as possible to -enable the timestamp cache. Once cbmem is available, the values will be -transferred automatically. - -All regions are automatically reset on initialization. - -Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init -------------------------------------------------------------------------------------- - -timestamp_init will set up a local cache. cbmem must be initialized before that -cache vanishes - as happens when jumping to the next stage. - -Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init --------------------------------------------------------------------------------------- - -This case is not supported right now, just don't call timestamp_init after -cbmem_initialize. (Patches to make this more robust are welcome.) - -Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init ---------------------------------------------------------------------------------- - -We always reset the cbmem region before using it, so pre-suspend timestamps -will be gone. - -Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init ----------------------------------------------------------------------------------- - -We always reset the cbmem region before using it, so pre-suspend timestamps -will be gone.

1 0

Patch set updated for coreboot: Documentation: Add Kconfig document
by Martin Roth 07 Nov '16

07 Nov '16

Martin Roth (martinroth(a)google.com) just uploaded a new patch set to gerrit, which you can find at https://review.coreboot.org/16947 -gerrit commit ef2174403c48b61f193e6b9b06ba3f8f7560d311 Author: Martin Roth <martinroth(a)google.com> Date: Sat Oct 8 22:40:52 2016 -0600 Documentation: Add Kconfig document Change-Id: I99ca65343d52e99611644c0c65f4b7feb5c58436 Signed-off-by: Martin Roth <martinroth(a)google.com> --- Documentation/core/Kconfig.md | 934 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 934 insertions(+) diff --git a/Documentation/core/Kconfig.md b/Documentation/core/Kconfig.md new file mode 100644 index 0000000..8fe9752 --- /dev/null +++ b/Documentation/core/Kconfig.md @@ -0,0 +1,934 @@ +# Kconfig in coreboot + + +## Document History +- Initial Version: June 15, 2015 +- First public version: October 8, 2016 + + +## Overview +Kconfig is a tool used in coreboot, Linux, and many other projects as the main configuration mechanism. In coreboot, it allows a developer both to select which platform to build and to modify various features within the platform. The Kconfig language was developed as a way to configure the Linux kernel, and is still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45, the ncurses based menuconfig was added, which is still used as the main configuration front end in coreboot today. + +The official Kconfig source and documentation is kept at kernel.org: + +- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tre… +- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-lang… + +The advantage to using Kconfig is that it allows users to easily select the high level features of the project to be enabled or disabled at build time. Ultimately the Kconfig tool generates a list of values which are used by the source code and Makefiles of the project. This allows the source files to select features, and allows the build to determine which files should be compiled and linked to the rom. + + +## Kconfig targets in Make +The Kconfig program in coreboot is built from source in util/kconfig. There are various targets in the makefile to build Kconfig in different ways. These give the user control over how to build the platform + + +### Front end configuration targets +These are the make targets that would be used to update the configuration of the platform. +- config - Text mode configuration tool, asks each configuration option in turn. This does actually run in coreboot, but it is recommended that this not be used as there is no way to save a partial config. +- gconfig - Graphical configuration tool based on GTK+ 2.0. +- menuconfig - Text mode, menu driven configuration tool. +- nconfig - Text mode, menu driven configuration tool. +- xconfig - Graphical front end based on QT. + + +### Targets that update config files +These options are used to update the coreboot config files, typically .config. The target file can be changed with variables in the environment or on the make command line. + +- defconfig - This generates a config based on another config file. Use the environment variable KBUILD_DEFCONFIG to specify the base config file. +- oldconfig - Displays the answers to all configuration questions as it generates the config.h file. If an interactive question is found that does not have an answer yet, it stops and queries the user for the desired value. +- olddefconfig - Generates a config, using the default value for any symbols not listed in the .config file. +- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols that were left as default values. This is very useful for debugging, and is how config files should be saved. +- silentoldconfig - This evaluates the .config file the same way that the oldconfig target does, but does not print out each question as it is evaluated. It still stops to query the user if an option with no answer in the .config file is found. + + +### Targets not typically used in coreboot +- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These are all used to generate various Kconfig files for testing. + + +### Environment Variables that affect Kconfig +These variables are typically set in the makefiles or on the make command line. + +#### Variables added to the coreboot Kconfig source +These variables were added to Kconfig specifically for coreboot and are not included in the Linux version. + +- COREBOOT_BUILD_DIR=path for temporary files. This is used by coreboot’s abuild tool. + +- KCONFIG_STRICT=value. Define to enable warnings as errors. This is enabled in coreboot, and should not be changed. + +- KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file (build/config.h). This is enabled in coreboot, and should not be changed. + + +#### Variables used to control the input and output config files +- KBUILD_DEFCONFIG=inputname of the defconfig file. This defaults to ‘configs/defconfig’ and is used by the ‘defconfig’ target + +- DEFCONFIG=output name of the defconfig file. This defaults to ‘defconfig’ and is used by ‘savedefconfig’ target as the output filename + +- DOTCONFIG=name of the .config file. This defaults to '.config' and is used by most config type targets + + +#### Variables used by the makefiles for controlling Kconfig +- Kconfig=root Kconfig file. This is set to 'src/Kconfig' in the coreboot makefile. + +- KCONFIG_CONFIG=input config file. coreboot sets this to $(DOTCONFIG). + +- KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this to $(obj)/config.h. + +- KCONFIG_DEPENDENCIES=”kbuild dependency file’. This defaults to auto.conf.cmd and outputs the name of all of the Kconfig files used. + +- KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”. coreboot sets this to $(obj)/config. + +#### Used only for ‘make menuconfig’ +- MENUCONFIG_MODE=single_menu. set to "single_menu" to enable. All other values disable the option. This makes submenus appear below the menu option instead of opening a new screen. + +- MENUCONFIG_COLOR=<theme>. This sets the color theme for the menu from these options: + + - mono => selects colors suitable for monochrome displays. + - blackbg => selects a color scheme with black background. + - classic => theme with blue background. The classic look. + - bluetitle => an LCD friendly version of classic. (default). + + +#### Used only for ‘make nconfig’ + +- NCONFIG_MODE=single_menu + + Submenus appear below the menu option instead of opening a new screen. + + +#### Unused in coreboot + +Although these variables are not used by coreboot, their values should be left at the default values. Other values may have unexpected effects on the codebase. + +- KCONFIG_SEED=randconfig seed value +- KCONFIG_PROBABILITY=randconfig percent to set to y +- KCONFIG_NOSILENTUPDATE=value. Define to prevent silent updates to .config file +- KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink +- KCONFIG_TRISTATE=filename of tristate.conf file +- SRCTREE=path to src directory +- KCONFIG_AUTOCONFIG=path and filename of the auto.conf file + + coreboot sets this to $(obj)/auto.conf. Although this value is actually set by coreboot, the resulting file is not used. + +- CONFIG_=prefix for Kconfig output symbols + + coreboot expects this to *NOT* be set. + + + +## Kconfig Language + +The Kconfig language has about 30 keywords, some overloaded, and some with the same meaning. Whitespace may have specific meaning, for example in the "help" keyword. There are 8 logical operators for use in expressions, which allow values to be set based on other values. + + +### Terminology + +- Symbols - There are two types of symbols, "constant" and “non-constant”. + - Constant symbols are alphanumeric values used in expressions for comparison. The Kconfig language specification says that these must be surrounded by single or double quotes. + - Non-constant symbols are the 'config' values that are output into the saved .config, auto.conf and config.h files. Non-constant symbols are typically defined with the 'config' keyword, although they can also be defined with the 'choice' keyword. These symbols may be used in a file's expressions before they are defined. Valid characters for non-constant symbols are any combination of alphanumeric characters, underscore. Although “1234” is accepted as a symbol name, as is “o_o”, convention is to use all uppercase words that are descriptive of the symbol's use so they make sense when turned into CONFIG_NAME #defines + +- Expressions - An expression is a logical evaluation. It can be as simple as a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be complex evaluations of multiple symbols using the various logical operators. The Kconfig language allows these logical evaluations in several places. The most common use for complex expressions is following 'if' or ‘depends on’ keywords, but they can also be used to set the value for a prompt or default values. + +- Types - Each Kconfig symbol is one of the following types: bool, hex, int, string, or tristate. The tristate type is not used for coreboot, leaving just four types. As noted in the keyword summaries, a symbol must have a consistent type anywhere it is defined. Also, Kconfig will simply not display a symbol that has no type defined. A warning will be displayed in the terminal where menuconfig was run if this happens: _src/Kconfig:25:warning: config symbol defined without type_. + +- Prompts - Input prompts are the text associated with the symbols which shown to the user. The Kconfig language definition does not require surrounding the prompt’s text with quotes, however it is recommended that quotes be used for maximum compatibility. + +- Menu Entries - These keyword blocks create the symbols and questions that are visible in the front end. + + +## Keywords + +### bool + +The 'bool' keyword assigns a boolean type to a symbol. The allowable values for a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt string which makes the symbol editable in one of the configuration front ends. + + +##### Usage: +bool \[prompt\] \[if <expr>\] + + +##### Example: + config ANY_TOOLCHAIN + bool "Allow building with any toolchain" + default n + depends on COMPILER_GCC + + +##### Notes: +- Putting the prompt after the 'bool' keyword is the same as using a 'prompt' keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching definitions are fine, although unnecessary. Conflicting type definitions will be ignored, and a warning will be presented on the console where the configuration front end was run: _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + +- Boolean symbols do not need a default and will default to ‘n’. + + +##### Restrictions: + +- This keyword must be within a symbol definition block, started by the 'config' keyword. + +-------------------------------------------------------------------------------- + +### choice + +This creates a selection list of one or more boolean symbols. For bools, only one of the symbols can be selected, and one will be be forced to be selected, either by a ‘default’ statement, or by selecting the first config option if there is no default value listed. + +##### Usage: +choice \[symbol\] +- \[prompt\] +- \[default\] + + +##### Example: + choice TESTCHOICE + prompt "Test choice" + default TESTCHOICE2 if TESTCHOICE_DEFAULT_2 + default TESTCHOICE3 + + config TESTCHOICE1 + bool "Choice 1" + config TESTCHOICE2 + bool "Choice 2" + config TESTCHOICE3 + bool "Choice 3" + config TESTCHOICE4 + bool "Choice 4" if TESTCHOICE_SHOW_4 + endchoice + + config TESTCHOICE_DEFAULT_2 + def_bool y + + config TESTCHOICE_SHOW_4 + def_bool n + + config TESTSTRING + string + default “String #1” if TESTCHOICE1 + default “String #2” if TESTCHOICE2 + default “String #4” if TESTCHOICE3 + default “String #4” if TESTCHOICE4 + default “” + + +##### Notes: +- If no symbol is associated with a choice, then you can not have multiple definitions of that choice. If a symbol is associated to the choice, then you may define the same choice (ie. with the same entries) in another place. Any selection in either location will update both choice menu selections. In coreboot, the value of the symbol is always 1. +- As shown in the example above, the choice between bools can be used to set the default for a non-bool type. This works best when the non-bool type does not have an input prompt. + + +##### Restrictions: +- Symbols used for 'choice' entries must have input prompts defined using the 'prompt' keyword. +- Symbols used in 'choice' entries may not be enabled with a 'select' statement, they can be defaulted using a second Kconfig symbol however. + +-------------------------------------------------------------------------------- + +### comment + +This keyword defines a line of text that is displayed to the user in the configuration frontend and is additionally written to the output files. + + +##### Usage: +comment <prompt> +- \[depends on\] + + +##### Example: + + if CONSOLE_SERIAL + comment "I/O mapped, 8250-compatible" + depends on DRIVERS_UART_8250IO + endif + + +##### Notes: +- Comments are only valid outside of config blocks, but can be within menu and if blocks. + +-------------------------------------------------------------------------------- + +### config + +This is the keyword that starts a block defining a Kconfig symbol. The symbol modifiers follow the 'config' statement. + +##### Usage: +config <symbol> + +- \[bool | def_bool | int | hex | string\] +- \[depends on\] +- \[prompt\] +- \[help\] +- \[range\] +- \[select\] + + +##### Example: + config SEABIOS_PS2_TIMEOUT + prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS + default 0 + depends on PAYLOAD_SEABIOS + int + help + Some PS/2 keyboard controllers don't respond to commands + immediately after powering on. This specifies how long + SeaBIOS will wait for the keyboard controller to become + ready before giving up. + + +##### Notes: +- non-coreboot projects also use the 'tristate' and 'def_tristate' types. +- ends at the next Kconfig keyword that is not valid inside the config block: + + menu | endmenu | if | endif | choice | config | source | comment + +-------------------------------------------------------------------------------- + +### default + +The ‘default’ keyword assigns a value to a symbol in the case where no preset value exists, i.e. the symbol is not present and assigned in .config. If there is no preset value, and no ‘default’ keyword, the user will be asked to enter a valid value when building coreboot. + + +##### Usage: +default <expr> \[if <expr>\] + + +##### Example: + config GENERATE_MP_TABLE + prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC + bool + default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC + help + Generate an MP table (conforming to the Intel + MultiProcessor specification 1.4) for this board. + + +##### Notes: +- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal symbol definitions in a .config file. The default only affects the symbol if there is no valid definition in a config file. This is a frequent source of confusion. It’s covered again in the Tips section below. +- The first valid 'default' entry for a symbol is always used. Any further 'default' statements for a symbol are ignored. This means that the order of Kconfig files is very important as the earlier files get to set the defaults first. They should be sourced in the order from most specific (mainboard Kconfig files) to the most generic (architecture-specific Kconfig files). +- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or “” depending on the type, however the 'bool' type is the only type that should be left without a default value. + +-------------------------------------------------------------------------------- + +### def_bool + +‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to boolean. It lets you set the type and default value at the same time, instead of setting the type and the prompt at the same time. It's typically used for symbols that don't have prompts. + + +##### Usage: +def_bool <expr> \[if <expr>\] + + +##### Example: + config EC_GOOGLE_CHROMEEC_LPC + depends on EC_GOOGLE_CHROMEEC && ARCH_X86 + def_bool y + select SERIRQ_CONTINUOUS_MODE + help + Google Chrome EC via LPC bus. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching definitions are fine, although unnecessary. Conflicting type definitions will be ignored, and a warning will be presented on the console where the configuration front end was run: _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' keyword. + +-------------------------------------------------------------------------------- + +### depends on + +This defines a dependency for a menu entry, including symbols and comments. It behaves the same as surrounding the menu entry with an if/endif block. If the ‘depends on’ expression evaluates to false, the 'prompt' value will not be printed, and defaults will not be set based on this block. + + +##### Usage: +depends on <expr> + + +##### Example: + config COMMON_CBFS_SPI_WRAPPER + bool + default n + depends on SPI_FLASH + depends on !ARCH_X86 + help + Use common wrapper to interface CBFS to SPI bootrom. + + +##### Notes: +- Symbols that have multiple ‘depends on’ sections as above are equivalent to a single ‘depends on’ statement with sections joined by &&. So the above is the same as “depends on SPI_FLASH && ! ARCH_X86”. + +-------------------------------------------------------------------------------- + +### endchoice + +This ends a choice block. See the 'choice' keyword for more information and an example. + +-------------------------------------------------------------------------------- + +### endif + +This ends a block started by the 'if' keyword. See the 'if' keyword for more information and an example. + +-------------------------------------------------------------------------------- + +### endmenu + +This ends a menu block. See the 'menu' keyword for more information and an example. + +-------------------------------------------------------------------------------- + +### help + +The 'help' keyword defines the subsequent block of text as help for a config or choice block. The help block is started by the 'help' keyword on a line by itself, and the indentation level of the next line controls the end of the help block. The help ends on the next non-blank line that has an indentation level less than the indentation level of the first line following the 'help' keyword. +' +##### Usage: +help <help text> + + +##### Example: + config COMPILER_GCC + bool "GCC" + help + Use the GNU Compiler Collection (GCC) to build coreboot. For details see http://gcc.gnu.org. + + +##### Notes: +- Identical to the '---help---' keyword which isn’t used in coreboot. +- Other keywords are allowed inside the help block, and are not recognized as keywords so long as the indentation rules are followed, even if they start a line. + + +##### Restrictions: +- only used for 'config' and 'choice' keywords. + +-------------------------------------------------------------------------------- + +### hex + +This is another symbol type specifier, specifying an unsigned integer value formatted as hexadecimal. + +##### Usage: +hex <expr> \[if <expr>\] + + +##### Example: + config INTEL_PCH_UART_CONSOLE_NUMBER + hex "Serial IO UART number to use for console" + default 0x0 + depends on INTEL_PCH_UART_CONSOLE + + +##### Notes: +- Kconfig doesn’t complain if you don’t start the default value for a hex symbol with ‘0x’, but not doing so will lead to issues. It will update 10 to 0x10 without warning the user. +- Putting the prompt text after the 'hex' keyword is the same as using a 'prompt' keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching definitions are fine, although unnecessary. Conflicting type definitions will be ignored, and a warning will be presented on the console where the configuration front end was run: _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' keyword. +- Hex types must have a 'default' entry set. + +-------------------------------------------------------------------------------- + +### if + +The 'if' keyword is overloaded, used in two different ways. The first definition enables and disables various other keywords, and follows the other keyword definition. This usage is shown in each of the other keywords' usage listings. + +The second usage of the 'if' keyword is part of an if/endif block. Most items within an if/endif block are not evaluated, while others, such as the 'source' keyword, ignore the existence of the if/endif block completely. Symbols defined within an if/endif block are still created, although their default values are ignored - all values are set to 'n'. + + +##### Usage: +if <expr> + +- \[config\] +- \[choice\] +- \[comment\] +- \[menu\] + +endif + + +##### Example: + if ARCH_X86 + + config SMP + bool + default y if MAX_CPUS != 1 + default n + help + This option is used to enable certain functions to make + coreboot work correctly on symmetric multi processor (SMP) systems. + endif + +##### Restrictions: +- Corresponding ‘if’ and ‘endif’ statements must exist in the same file. + +-------------------------------------------------------------------------------- + +### int + +A type setting keyword, defines a symbol as an integer, accepting only signed numeric values. The values can be further restricted with the ‘range’ keyword. + + +##### Usage: +int <expr> \[if <expr>\] + + +##### Example: + config PRE_GRAPHICS_DELAY + int "Graphics initialization delay in ms" + default 0 + help + On some systems, coreboot boots so fast that connected + monitors (mostly TVs) won't be able to wake up fast enough + to talk to the VBIOS. On those systems we need to wait for a + bit before executing the VBIOS. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching definitions are fine, although unnecessary. Conflicting type definitions will be ignored, and a warning will be presented on the console where the configuration front end was run: _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' keyword. +- Int types must have a default value set. + +-------------------------------------------------------------------------------- + +### mainmenu + +The 'mainmenu' keyword sets the title or title bar of the configuration front end, depending on how the configuration program decides to use it. It can only be specified once and at the very beginning of the top level Kconfig file, before any other statements. + + +##### Usage: +mainmenu <prompt> + +##### Example: +mainmenu "coreboot configuration" + +##### Restrictions: +- Must be the first statement in the top level Kconfig. +- Must only be used once in the entire Kconfig tree. + +-------------------------------------------------------------------------------- + +### menu + +The 'menu'/'endmenu' pair of keywords tell the configuration front end that the enclosed statements are part of a group of related pieces. + + +##### Usage: +menu <prompt> + +- \[choice\] +- \[config\] +- \[menu\] +- \[if/endif\] + +endmenu + + +##### Example: + menu "On-Chip Device Power Down Control" + config TEMP_POWERDOWN + bool "Temperature sensor power-down" + + config SATA_POWERDOWN + bool "SATA power-down" + + config ADC_POWERDOWN + bool "ADC power-down" + + config PCIE0_POWERDOWN + bool "PCIE0 power-down" + + config MAC_POWERDOWN + bool "MAC power-down" + + config USB1_POWERDOWN + bool "USB2.0 Host Controller 1 power-down" + + config IDE_POWERDOWN + bool "IDE power-down" + + endmenu + +##### Restrictions: +- Must be closed by a corresponding ‘endmenu’ keyword in the same file. + +-------------------------------------------------------------------------------- + +### prompt + +The 'prompt' keyword sets the text displayed for a config symbol or choice in configuration front end. + + +##### Usage: +prompt <prompt> \[if <expr>\] + + +##### Example: + config REALMODE_DEBUG + prompt "Enable debug messages for option ROM execution" + bool + default n + depends on PCI_OPTION_ROM_RUN_REALMODE + depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8 + help + This option enables additional x86emu related debug + messages. Note: This option will increase the time to emulate a ROM. + + If unsure, say N. + + +##### Notes: +- The same rules apply for menu entries defined by the 'prompt' keyword and other prompt types such as those defined by the 'int' or 'string' keywords. +- Redefining the prompt text in multiple instances of config symbols is allowed. Only the current prompt statement for a particular entry will be displayed by the front end in any given location. This means that multiple mainboards can set different prompt values for a symbol, and it would appear differently in each mainboard’s menu. The symbol can even have multiple entries in the same menu with different prompts if desired. For example, both of these would get printed, and changing either entry would change the other. + config PROMPT_TEST + string "Prompt value 1" + + config PROMPT_TEST + prompt "Prompt value 2" + +- Although not required, it's recommended that you use quotes around prompt statements. +* If the prompt is redefined inside the SAME config entry, you will get a warning: _warning: prompt redefined_. For example, this is not allowed: + + + config PROMPT_TEST + string "Prompt value 1" + prompt "Prompt value 2" +-------------------------------------------------------------------------------- + +### range + +This sets the allowable minimum and maximum entries for hex or int type config symbols. + + +##### Usage: +range <symbol> <symbol> \[if <expr>\] + + +##### Example: + config TEST1 + hex "test 1" + range 0x0 0x10 + + +##### Notes: +- Only the first definition of a range is used for any symbol. Further definitions will be ignored without warning. + +-------------------------------------------------------------------------------- + +### select + +The ‘select’ keyword is used within a bool type config block. In coreboot (and other projects that don't use modules), the 'select' keyword can force an unassociated bool type symbol to 'y'. When the symbol for the config block is ‘y’, the ‘select’ action is taken. Otherwise the bool is unaffected. + + +##### Usage: +select <symbol> \[if <expr>\] + + +##### Example: + config TPM + bool + default n + select LPC_TPM if ARCH_X86 + select I2C_TPM if ARCH_ARM + select I2C_TPM if ARCH_ARM64 + help + Enable this option to enable TPM support in coreboot. + If unsure, say N. + +##### Notes: +- Using the 'select' keyword can create logical contradictions in Kconfig, which will create warnings and fail to save the .config. Following is an example of an obviously invalid configuration, where selecting BOOLTEST violates the ‘depends on’ of BOOLTEST2: + + config BOOLTEST + bool "bool Test" + select BOOLTEST2 + + config BOOLTEST2 + bool "Bool Test 2" + depends on !BOOLTEST + +##### Restrictions: +- The ‘select’ keyword only works on bool type symbols. +- Symbols created inside of choice blocks cannot be selected, and should be enabled by using default values instead. + +-------------------------------------------------------------------------------- + +### source + +The 'source' keyword functions much the same as an 'include' statement in c. This pulls one or more files into Kconfig at the location of the 'source' command. This statement is always parsed - there is no way to conditionally source a file. coreboot has modified the source statement slightly to handle directory globbing. The '*' character will match with any directory. + + +##### Usage: +source <prompt> + + +##### Example: + + choice + prompt "Mainboard vendor" + default VENDOR_EMULATION + + source "src/mainboard/*/Kconfig.name" + + endchoice + + source "src/mainboard/*/Kconfig" + + +##### Notes: +- As with all prompt values, the 'source' prompt may be enclosed in single or double quotes, or left without any quotes. Using quotes is highly recommended however. +- The 'source' keyword loads files relative to the working directory where the Kconfig command was run. For coreboot, this is the root coreboot directory, so all source commands in the src directory need to start with ‘src/’. +- In coreboot's Kconfig, if a sourced file does not exist, the statement is simply ignored. This is different than other versions of Kconfig. +- 'source' pulls a file into the Kconfig tree at the location of the keyword. This allows for files containing small bits of the Kconfig tree to be pulled into a larger construct. A restriction on this is that the starting/ending keyword pairs must be within the same file - ‘endif’ cannot appear in a different file than the ‘if’ statement that it ends. The same is true of 'menu'/endmenu and 'choice'/'endchoice' pairs. + +The coreboot Kconfig structure uses this along with globbing to build up the mainboard directory. Each mainboard’s Kconfig.name file contains just two statements that generate a list of all the platform names: + + config BOARD_AMD_NORWICH + bool "Norwich" + + +##### Restrictions: +- 'source' keywords always load in the specified file or files. There is no way to optionally pull in a file. Putting an if/endif block around a source command does not affect the source command, although it does affect the content. To avoid confusion, use if/endif blocks inside sourced files to remove their content if necessary. + +-------------------------------------------------------------------------------- + +### string + +The last of the symbol type assignment keywords. 'string' allows a text value to be entered. + + +##### Usage: +string <expr> \[if <expr>\] + + +##### Example: + config BOOTBLOCK_SOUTHBRIDGE_INIT + string + default "southbridge/amd/pi/hudson/bootblock.c" + + config HUDSON_GEC_FWM_FILE + string "GEC firmware path and filename" + depends on HUDSON_GEC_FWM + + +##### Notes: +- Putting the prompt after the 'string' keyword is the same as using a 'prompt' keyword later. See the prompt keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching definitions are fine, although unnecessary. Conflicting type definitions will be ignored, and a warning will be presented on the console where the configuration front end was run: _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_. +- Some characters may not get interpreted correctly when inside a string entry depending on how they are used - inside a C file, inside a Makefile, passed through a Makefile to a C file, or something else. It may be necessary to escape the characters at times. Because this is very dependent upon how the symbol is actually used, a definitive guide cannot be given here. +- String type variables do NOT need a default, and will default to the value “”. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' keyword. + +-------------------------------------------------------------------------------- + + + + +## Keywords not used in coreboot at the time of writing: + +- allnoconfig_y: +- defconfig_list +- def_tristate +- env +- ---help--- +- menuconfig +- modules +- optional +- option +- tristate +- visible if + + +## Build files generated by Kconfig + +### build/config.h + +The config.h file is a very basic header file made up of a list of #define statements: + + #define SYMBOL NAME XXX + + +##### Symbol types: +- bool, int, and hex types - Every symbol of one of these types created in the Kconfig tree is defined. It doesn’t matter whether they’re in an ‘if - endif’ block, or have a ‘depends on’ statement - they ALL end up being defined in this file. +- String - Only string types that actually have a value associated with them are defined. + +The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values respectively. String values are placed inside double quotes. + +The name of the file is controlled by the $KCONFIG_AUTOHEADER environment variable, which is set to $(obj)/config.h by the coreboot makefiles. + +The prefix used for the symbols is controlled by the $CONFIG_ environment variable. This is not set in coreboot, which uses the default CONFIG_ prefix for all of its symbols. + +The coreboot makefile forces the config.h file to be included into all coreboot C files. This is done in Makefile.inc on the compiler command line using the “-include $(obj)/config.h” command line option. + +Example of various symbol types in the config.h file: + + #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String + #define CONFIG_CBFS_SIZE 0x00300000 # Hex + #define CONFIG_TTYS0_BAUD 115200 # Int + #define CONFIG_HAVE_ACPI_TABLES 1 # Bool enabled + #define CONFIG_EXPERT 0 # Bool disabled + #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0 # Bool excluded + + +### .config + +The .config file in the root directory is used as the input file, but also by the makefiles to set variable values. The main difference is that it does not contain all of the symbols. It excludes symbols defined in an if/endif block whose expression evaluated as false. Note that the symbol CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not present in the .config file. + +In addition, the .config file below contains the 'comment' prompt text from the Kconfig, separating the blocks. + + ## General setup ## + CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String + CONFIG_CBFS_SIZE=0x00300000 # Hex + CONFIG_TTYS0_BAUD=115200 # Int + CONFIG_HAVE_ACPI_TABLES=y # Bool enabled + # CONFIG_EXPERT is not set # Bool disabled + +This file is included directly by the makefile, and sets the CONFIG symbols so that they are available during the build process. + + +### build/auto.conf + +Although the controlling variable for the auto.conf filename, KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself is not used by coreboot. This file has the same syntax and structure as the .config file, but contains all symbols in the Kconfig tree, including those that are not enabled, or are excluded by if/endif blocks, or the 'depends on' keyword. The kconfig tool could be updated to not generate this file, but since it's not hurting anything, it's still being generated. + + + +## Defconfig or Miniconfig files + +Miniconfig files are the standard .config files with all of the symbols which are set to their default values stripped out. These files are very useful for debugging your config, as well as being the best way to store your .config file. If you store your config as a full config file, it will be much harder to maintain. Any Kconfig symbols with updated default values will retain their old values, and any symbols which have been removed will still remain in the file. Storing full config files just generally leads to a lot more maintenance than storing miniconfig files. + +The easiest way to generate the miniconfig file is by running + + make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file] + +DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’. + + +To turn the miniconfig back into a full config file, use one of the two targets: + + make olddefconfig DOTCONFIG=[input/output file] + +or + + make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file] + +In both of these cases, DOTCONFIG defaults to .config. + + + +## Editing and updating saved .config files + + +### Don’t save full config files + +Save miniconfig files, as mentioned in the previous section. + + +### Disable values with ‘# CONFIG_SYMBOL is not set’ + +A common mistake when trying to disable a value is to edit the .config file and change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t correctly disable the symbol. If the default value for the symbol is ‘n’ to begin with, this isn’t an issue - the symbol just gets ignored, and the default value is used. The problem is where the default for the symbol is ‘y’. When the bad entry in the .config file gets ignored, the value is set back to ‘y’, leading to much frustration. + +Always disable the Kconfig symbols in the .config file with the syntax: + + # CONFIG_SYMBOL is not set + +### Only the LAST instance of a symbol is used + +When reading in a saved .config file, Kconfig uses the LAST instance of a symbol that it comes across, and ignores any previous instances. This can be used to override symbols in a saved .config file by appending the new value to a config file. + +For example: + +A .config file that contains these two lines: + + # CONFIG_BOOLTEST is not set + CONFIG_BOOLTEST=y + +After running ‘make olddefconfig’, ends up with the value: + + CONFIG_BOOLTEST=y + +A case where this can be used is by a making a script to create two versions of a coreboot rom for a single platform. The first ROM could be built with serial console disabled, and the second ROM, built as a debug version, could have serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and setting it to enabled. + +## General Kconfig Tips and Notes + +### Default values for config options + +The FIRST valid default that the Kconfig parser comes across will be used for each symbol. This means that the organization of the tree is very important. The structure should go from most specific at the top of the Kconfig tree to the most general later in the tree. In coreboot, the mainboard directories get loaded first, as they are sourced very early in the src/Kconfig file. Chipset Kconfig files get sourced later, and the architecture specific Kconfig files get sourced even later. This allows the mainboards to set their defaults early, overriding the default values set in chipset or architecture. + +Due to this mechanism, a default defined early cannot be changed by a default set in a later Kconfig file. There are ways around this, involving 'depends on' statements, but they add additional variables which are generally just used internal to Kconfig. + + +### Select statement usage + +The 'select' keyword forces the value of a symbol with a bool type to 'y'. It overrides any dependencies of the symbol, so using it carelessly can lead to unpredictable results. + + + +### All bool, int, and hex Kconfig symbols are ALWAYS defined in C if they are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL + +String symbols are the exception. All others (int, hex, etc.) are always defined in config.h. Never use an #ifdef statement for a Kconfig symbol other than strings in C to determine whether the symbol is enabled or disabled. So long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if the symbol is only inside of an if/endif block where the if expression evaluates as false, the symbol STILL gets defined in the config.h file (though not in the .config file). + +Use \#if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols and defined-to-0 symbols alike). + + + +### Symbols with prompts use default values *ONLY* when they are initially created or enabled. + +Symbols with a prompt which may be user-modified are NOT updated to default values when changing between platforms or modifying other symbols. There are only two times the default values are used: + 1. When a config is initially created. + 2. When a dependency which had previously kept the symbol from being active changes to allowing it to be active. + +Because of this, starting with a saved .config for one platform and updating it for another platform can lead to very different results than creating a platform from scratch. + + + +### Symbols with no prompt will always be the default value (unless a 'select' is used). + +Symbols that do not have a prompt will always use the first valid default value specified in Kconfig. They cannot be updated, even if they are modified in a saved .config file. As always, a 'select' statement overrides any specified 'default' or 'depends on' statement. + + +## Differences between coreboot's Kconfig and other Kconfig implementations. + +- coreboot has added the glob operator '*' for the 'source' keyword. +- coreboot’s Kconfig always defines variables except for strings. In other Kconfig implementations, bools set to false/0/no are not defined. +- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux (where the macro comes from) it’s ‘true’ as soon as the variable is defined. +- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to error out if there are any issues in the Kconfig files. In the Linux kernel, Kconfig will generate a warning, but will still output an updated .config or config.h file. + + +## Kconfig Editor Highlighting + +#### vim: + +vim has syntax highlighting for Kconfig built in (or at least as a part of vim-common), but most editors do not. + + +#### ultraedit: + +[https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew](https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew) + + + +#### atom: + +[https://github.com/martinlroth/language-kconfig](https://github.com/martinlroth/language-kconfig) + + +## Syntax Checking: + +The Kconfig utility does some basic syntax checking on the Kconfig tree. Running "make silentoldconfig" will show any errors that the Kconfig utility sees. + +### util/kconfig_lint + +Because the Kconfig utility is relatively forgiving, and ignores issues that a developer might be interested in, kconfig_lint, another Kconfig checker has been written. + +The file kconfig_lint and its associated readme can be found in the coreboot utils/lint directory. It is useful for parsing the Kconfig tree, and for showing warnings, errors, and notes about coreboot’s Kconfig files. + + + kconfig_lint <options> + -o|--output=file Set output filename + -p|--print Print full output + -e|--errors_off Don't print warnings or errors + -w|--warnings_off Don't print warnings + -n|--notes Show minor notes + --path=dir Path to top level kconfig + -c|--config=file Filename of config file to load + -G|--no_git_grep Use standard grep tools instead of git grep + + +The -p option is very useful for debugging Kconfig issues, because it reads all of the Kconfig files in the order that the Kconfig tools would read them, and prints it out, along with where each line came from and which menu it appears in.

1 0

Patch merged into coreboot/master: pci_ids.h: Correct recent AMD ID names
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 463f46eb614ee047870a423ce90f78e4516ce012 Author: Marshall Dawson <marshalldawson3rd(a)gmail.com> Date: Fri Oct 14 20:46:08 2016 -0600 pci_ids.h: Correct recent AMD ID names Adjust the names to match AMD's convention for family and model. This patch is relevant for: Trinity & Richland: Family 15h Models 00h-0Fh Carrizo: Family 15h Models 60h-6Fh Mullins & Steppe Eagle: Family 16h Models 30h-3Fh Change-Id: I613b84ed438fb70269d789c9901f1928b5500757 Signed-off-by: Marshall Dawson <marshalldawson3rd(a)gmail.com> Reviewed-on: https://review.coreboot.org/17169 Reviewed-by: Martin Roth <martinroth(a)google.com> Tested-by: Martin Roth <martinroth(a)google.com> See https://review.coreboot.org/17169 for details. -gerrit

1 0

Patch merged into coreboot/master: mainboard/google/reef: update DMIC related pins configuration
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 50198c117839ee01c331a827dc57b6293c989f34 Author: Sathyanarayana Nujella <sathyanarayana.nujella(a)intel.com> Date: Mon Oct 31 10:48:43 2016 -0700 mainboard/google/reef: update DMIC related pins configuration CLK_B1(GPIO_80) and DATA_2(GPIO_83) pins needs to be configured as native mode to use them for DMIC record on other potential DMIC's. DMIC blobs configure the clocks. For stereo & quad channel record, both CLK_A1 and CLK_B1 are enabled. For mono channel record, only CLK_A1 is enabled. BUG=chrome-os-partner:56918 BRANCH=None TEST=During DMIC record, check CLK_B1 and DATA_2 lines Change-Id: I838009b85190de5360d593238e48c9593c1dc43a Signed-off-by: Sathyanarayana Nujella <sathyanarayana.nujella(a)intel.com> Reviewed-on: https://review.coreboot.org/17199 Tested-by: build bot (Jenkins) Reviewed-by: Aaron Durbin <adurbin(a)chromium.org> See https://review.coreboot.org/17199 for details. -gerrit

1 0

Patch merged into coreboot/master: soc/intel/apollolake: Add pmc_ipc device support
by gerrit＠coreboot.org 07 Nov '16

07 Nov '16

the following patch was just integrated into master: commit 37742f6870ec1d4b860769db25ef665cdb7c1615 Author: Lijian Zhao <lijian.zhao(a)intel.com> Date: Fri Oct 28 11:01:09 2016 -0700 soc/intel/apollolake: Add pmc_ipc device support A dedicated pmc_ipc DSDT entry is required for pmc_ipc kernel driver. The ACPI mode entry includes resources for PMC_IPC1, SRAM, ACPI IO and Punit Mailbox. BRANCH=None BUG=chrome-os-partner:57364 TEST=Boot up into OS successfully and check with dmesg to see the driver has been loaded successfully without errors. Change-Id: Ib0a300febe1e7fc1796bfeca1a04493f932640e1 Signed-off-by: Lijian Zhao <lijian.zhao(a)intel.com> Reviewed-on: https://review.coreboot.org/17181 Reviewed-by: Aaron Durbin <adurbin(a)chromium.org> Tested-by: build bot (Jenkins) See https://review.coreboot.org/17181 for details. -gerrit

1 0

Jump to page:

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

coreboot-gerrit November 2016