diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/AMD-S3.txt | 153 | ||||
| -rw-r--r-- | Documentation/CorebootBuildingGuide.tex | 1797 | ||||
| -rw-r--r-- | Documentation/Doxyfile.coreboot | 1639 | ||||
| -rw-r--r-- | Documentation/Doxyfile.coreboot_simple | 259 | ||||
| -rw-r--r-- | Documentation/Kconfig.tex | 480 | ||||
| -rw-r--r-- | Documentation/Makefile | 71 | ||||
| -rw-r--r-- | Documentation/POSTCODES | 26 | ||||
| -rw-r--r-- | Documentation/RFC/chip.tex | 266 | ||||
| -rw-r--r-- | Documentation/RFC/config.tex | 291 | ||||
| -rw-r--r-- | Documentation/abi-data-consumption.txt | 22 | ||||
| -rw-r--r-- | Documentation/beginverbatim.tex | 1 | ||||
| -rw-r--r-- | Documentation/cbfs.txt | 421 | ||||
| -rw-r--r-- | Documentation/codeflow.svg | 234 | ||||
| -rw-r--r-- | Documentation/coreboot_logo.png | bin | 0 -> 2236 bytes | |||
| -rw-r--r-- | Documentation/endverbatim.tex | 1 | ||||
| -rw-r--r-- | Documentation/gcov.txt | 227 | ||||
| -rw-r--r-- | Documentation/hypertransport.svg | 59 | ||||
| -rw-r--r-- | Documentation/submodules.txt | 46 |
18 files changed, 5993 insertions, 0 deletions
diff --git a/Documentation/AMD-S3.txt b/Documentation/AMD-S3.txt new file mode 100644 index 0000000000..48d4c8f3e7 --- /dev/null +++ b/Documentation/AMD-S3.txt @@ -0,0 +1,153 @@ + _____ ____ _____ ______ ____ ____ ____ _______ + / ____/ __ \| __ \| ____| _ \ / __ \ / __ \__ __| + | | | | | | |__) | |__ | |_) | | | | | | | | | + | | | | | | _ /| __| | _ <| | | | | | | | | + | |___| |__| | | \ \| |____| |_) | |__| | |__| | | | + \_____\____/|_| \_\______|____/ \____/ \____/ |_| + + __ __ _____ _____ ____ + /\ | \/ | __ \ / ____| |___ \ + / \ | \ / | | | | | (___ __) | + / /\ \ | |\/| | | | | \___ \ |__ < + / ____ \| | | | |__| | ____) | ___) | + /_/ \_\_| |_|_____/ |_____/ |____/ + + + S3 in Coreboot (V 1.2) +---------------------------------------- + Zheng Bao + <zheng.bao@amd.com> + <fishbaozi@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 new file mode 100644 index 0000000000..5b3eacf778 --- /dev/null +++ b/Documentation/CorebootBuildingGuide.tex @@ -0,0 +1,1797 @@ +% +% This document is released under the GPL +% Initially written by Stefan Reinauer, <stepan@coresystems.de> +% + +\documentclass[titlepage,12pt]{article} +\usepackage{a4} +\usepackage{graphicx} +\usepackage{url} +\usepackage[pdftex]{hyperref} +% \usepackage{makeidx} +% \makeindex + +\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 on AMD64}, + pdfauthor={Stefan Reinauer}, + pdfsubject={coreboot configuration and build process}, + pdfkeywords={coreboot, Opteron, AMD64, configuration, Build} +} + + +% \newcommand{\sh}[1]{\begin{verbatim}\texttt{#1}\end{verbatim}} +% \newcommand{\prog}[1]{\textit{#1}} + +\setlength{\parindent}{0pt} + +\title{coreboot on AMD64} +\author{Stefan Reinauer $<$stepan@coresystems.de$>$} +\date{April 19th, 2009} + +\begin{document} + +\maketitle + +\thispagestyle{empty} + +\tableofcontents + +\newpage + +% +% 1 Abstract +% + +\section{Abstract} + +This document targets porting coreboot to new mainboards and creating +custom firmware images using coreboot. It describes how to build +coreboot images for the AMD64 platform, including hypertransport +configuration and pertinent utilities. If you are missing information or +find errors in the following descriptions, contact +\href{mailto:stepan@coresystems.de}{\textit{Stefan Reinauer $<$stepan@coresystems.de$>$}} + + +% +% 2 Changes +% + +\section{Changes} + \begin{itemize} + \item 2009/04/19 replace LinuxBIOS with coreboot + \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ + \item 2004/02/10 acpi and option rom updates + \item 2003/11/18 initial release + \end{itemize} + + + +% +% 3 What is coreboot +% + +\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. + +% +% 4 Build Requirements +% + +\section{Build Requirements} +To build coreboot for AMD64 from the sources you need a recent Linux +system for x86 or AMD64. SUSE Linux 8.2 or 9.0 are known to work fine. +The following toolchain is recommended: + + \begin{itemize} + \item GCC 3.3.1 + \item binutils 2.14.90.0.5 + \item Python 2.3 + \item CVS 1.11.6 + \end{itemize} + +\textbf{NOTE:} Later versions should also work. Prior versions might lead to problems. + +\newpage + +% +% 5 Getting the Sources +% + +\section{Getting the Sources} + +The latest coreboot sources are available via subversion. The subversion +repository is maintained at SourceForge.net (the project name is +\emph{FreeBIOS}). First you should create a directory for your +coreboot trees: + +{ \small +\begin{verbatim} +$ mkdir coreboot +$ cd coreboot +\end{verbatim} +} + +You can get the entire source tree via SVN: + +{ \small +\begin{verbatim} +$ svn co svn://coreboot.org/repos/trunk/coreboot-v2 +\end{verbatim} +} + +Once the source tree is checked out, it can be updated with: + +{ \small +\begin{verbatim} +% svn update +\end{verbatim} +} + +For the case your corporate firewall blocks port 3690 (subversion) we set up a +snapshot site that keeps the last few hundred source code revisions. It +is available at \url{http://qa.coreboot.org/}. +Due to major structural enhancements to \hbox{coreboot}, AMD64 support +is only available in the \texttt{coreboot-v2} tree. This tree reflects (as +of November 2003) coreboot version 1.1.5 and will lead to coreboot 2.0 +when finished. Most x86 hardware is currently only supported by the +coreboot 1.0 tree. + +% +% 6 coreboot configuration overview +% + +\section{coreboot configuration overview} +To support a large variety of existing hardware coreboot allows for a +lot of configuration options that can be tweaked in several ways: + +\begin{itemize} +\item +Firmware image specific configuration options can be set in the image +configuration file which is usually found in +\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/}. Such +options are the default amount of output verbosity during bootup, image +size, use of fallback mechanisms, firmware image size and payloads +(Linux Kernel, Bootloader...) The default configuration file name is +\texttt{Config.lb}, but coreboot allows multiple configurations to +reside in that directory. + +\item Mainboard specific configuration options can be set in the +mainboard configuration file placed in +\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$}. The +mainboard configuration file is always called \texttt{Config.lb}. It +contains information on the onboard components of the mainboard like +CPU type, northbridge, southbridge, hypertransport configuration and +SuperIO configuration. This configuration file also allows to include +addon code to hook into the coreboot initialization mechanism at +basically any point. + +\end{itemize} + +This document describes different approaches of changing and configuring the +coreboot source tree when building for AMD64. + +% +% 7 Building coreboot +% + +\section{Building coreboot} +One of the design goals for building coreboot was to keep object files +out of the source tree in a separate place. This is mandatory for +building parallel coreboot images for several distinct mainboards +and/or platforms. Therefore building coreboot consists of two steps: +\begin{itemize} +\item +creating a build tree which holds all files automatically created by the +configuration utility and the object files +\item +compiling the coreboot code and creating a flashable firmware image. +\end{itemize} + +The first of these two steps is accomplished by the \texttt{buildtarget} +script found in \texttt{coreboot-v2/targets/}. To build coreboot for +instance for the AMD Solo Athlon64 mainboard enter: + +\begin{verbatim} +% cd coreboot-v2/targets +% ./buildtarget amd/solo +\end{verbatim} + +This will create a directory containing a Makefile and other software +components needed for this build. The directory name is defined in the +firmware image specific configuration file. In the case of AMD's Solo +mainboard the default directory resides in +\texttt{coreboot-v2/targets/amd/solo/solo}. To build the coreboot image, do + +\begin{verbatim} +% cd amd/solo/solo +% make +\end{verbatim} + +The coreboot image filename is specified in the firmware image specific +configuration file. The default filename for AMD's Solo mainboard is +\texttt{solo.rom}. + +% +% 8 Programming coreboot to flash memory +% + +\section{Programming coreboot to flash memory} +The image resulting from a coreboot build can be directly programmed to +a flash device, either using a hardware flash programmer or by using the +Linux flash driver devbios or mtd. This document assumes that you use a +hardware flash programmer. If you are interested in doing in-system +software flash programming, find detailed information: + +\begin{itemize} +\item \url{http://www.openbios.org/development/devbios.html} (/dev/bios) +\item \url{http://www.linux-mtd.infradead.org/} (Memory Technology Device Subsystem MTD) +\end{itemize} + +\newpage + +% +% 9 coreboot configuration +% + +\section{coreboot configuration} +The following chapters will cope with configuring coreboot. All +configuration files share some basic rules +\begin{itemize} +\item +The default configuration file name in coreboot is \texttt{Config.lb}. +\item +All variables used in a configuration file have to be declared in this +file with \texttt{uses VARNAME} before usage. +\item +Comments can be added on a new line by using the comment identifier +\texttt{\#} at the beginning of the line. +\item +coreboot distinguishes between statements and options. Statements cause +the coreboot configuration mechanism to act, whereas options set +variables that are used by the build scripts or source code. +\item +Default configuration values can be set in the mainboard configuration +files (keyword default) +\item +Option overrides to the default configuration can only be specified in +the build target configuration file +\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb} +(keyword option) +\end{itemize} + +\subsection{Common Configuration Statements} + +\begin{itemize} + +\item \begin{verbatim}uses\end{verbatim} + +All local configuration variables have to be declared before they can be +used. Example: +\begin{verbatim} + uses CONFIG_ROM_IMAGE_SIZE +\end{verbatim} + +\textbf{NOTE:} Only configuration variables known to the configuration +system can be used in configuration files. coreboot checks +\texttt{coreboot-v2/src/config/Options.lb} to see whether a configuration +variable is known. + +\item \begin{verbatim}default\end{verbatim} + +The \texttt{default} statement is used to set a configuration variable +with an overridable default value. It is commonly used in mainboard +configuration files. + +Example: + +\begin{verbatim} + default CONFIG_ROM_IMAGE_SIZE=0x10000 +\end{verbatim} + +It is also possible to assign the value of one configuration variable to +another one, i.e.: + +\begin{verbatim} + default CONFIG_FALLBACK_SIZE=CONFIG_ROM_SIZE +\end{verbatim} + +Also, simple expressions are allowed: + +\begin{verbatim} + default CONFIG_FALLBACK_SIZE=(CONFIG_ROM_SIZE - NORMAL_SIZE) +\end{verbatim} + +If an option contains a string, this string has to be protected with +quotation marks: + +\begin{verbatim} + default CC="gcc -m32" +\end{verbatim} + +\item \begin{verbatim}option\end{verbatim} + +The \texttt{option} statement basically behaves identically to the +\texttt{default} statement. But unlike default it can only be used in +build target configuration files +(\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$}). The option +statement allows either to set new options or to override default values +set with the default statement in a mainboard configuration file. +Syntax and application are the same as with default. + +\end{itemize} + +\subsection{Firmware image specific configuration} +coreboot allows to create different firmware images for the same +hardware. Such images can differ in the amount of output they produce, +the payload, the number of subimages they consist of etc. + +The firmware image specific configuration file can be found in \\ +\texttt{coreboot-v2/targets/$<$vendor$>$/<mainboard$>$}. + +\subsubsection{Firmware image specific keywords} +In addition to the above described keywords the following statements are +available in firmware image specific configuration files: + +\begin{itemize} +\item \begin{verbatim}romimage\end{verbatim} + +The \texttt{romimage} definition describes a single rom build within the +final coreboot image. Normally there are two romimage definitions per +coreboot build: \texttt{normal} and \texttt{fallback}. + +Each \texttt{romimage} section needs to specify a mainboard directory and a +payload. The mainboard directory contains the mainboard specific +configuration file and source code. It is specified relatively to +\texttt{coreboot-v2/src/mainboard}. The payload definition is an absolute +path to a static elf binary (i.e Linux kernel or etherboot) + +\begin{verbatim} +romimage "normal" + option CONFIG_USE_FALLBACK_IMAGE=0 + option CONFIG_ROM_IMAGE_SIZE=0x10000 + option COREBOOT_EXTRA_VERSION=".0Normal" + mainboard amd/solo + payload /suse/stepan/tg3ide_ + disk.zelf +end +\end{verbatim} + +\item \begin{verbatim}buildrom\end{verbatim} + +The \texttt{buildrom} statement is used to determine which of the +coreboot image builds (created using \texttt{romimage}) are packed +together to the final coreboot image. It also specifies the order of +the images and the final image size: + +\begin{verbatim} + buildrom ./solo.rom CONFIG_ROM_SIZE "normal" "fallback" +\end{verbatim} + +\end{itemize} + + +\subsubsection{Firmware image configuration options} +In addition to the definitions described above there are a number of +commonly used options. Configuration options set in the firmware image +specific configuration file can override default selections from the +Mainboard specific configuration. See above examples about +option on how to set them. + +\begin{itemize} + +\item \begin{verbatim}CC\end{verbatim} + +Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to +\texttt{gcc -m32} for compiling AMD64 coreboot images on an AMD64 +machine. + +\item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim} + +Use new \textit{chip\_configure} method for configuring (nonpci) +devices. Set to \texttt{1} for all AMD64 mainboards. + +\item \begin{verbatim}CONFIG_DEFAULT_CONSOLE_LOGLEVEL\end{verbatim} + +Console will log at this level unless changed. Default is \texttt{7}, +minimum is \texttt{0}, maximum is \texttt{10}. + +\item \begin{verbatim}CONFIG_CONSOLE_SERIAL8250\end{verbatim} + +Log messages to 8250 uart based serial console. Default is \texttt{0} +(don't log to serial console). This value should be set to \texttt{1} +for all AMD64 builds. + +\item \begin{verbatim}CONFIG_ROM_SIZE\end{verbatim} + +Size of final ROM image. This option has no default value. + +\item \begin{verbatim}CONFIG_FALLBACK_SIZE\end{verbatim} + +Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:} +This does not include the fallback payload. + +\item \begin{verbatim}CONFIG_HAVE_OPTION_TABLE\end{verbatim} + +Export CMOS option table. Default is \texttt{0}. Set to \texttt{1} if +your mainboard has CMOS memory and you want to use it to store +coreboot parameters (Loglevel, serial line speed, ...) + +\item \begin{verbatim}CONFIG_ROM_PAYLOAD\end{verbatim} + +Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_PAYLOAD}, which +will boot from an IDE disk) + +\item \begin{verbatim}CONFIG_HAVE_FALLBACK_BOOT\end{verbatim} + +Set to \texttt{1} if fallback booting is required. Defaults to +\texttt{0}. + +\end{itemize} + + +The following options should be used within a romimage section: + +\begin{itemize} + +\item \begin{verbatim}CONFIG_USE_FALLBACK_IMAGE\end{verbatim} + +Set to \texttt{1} to build a fallback image. Defaults to \texttt{0} + +\item \begin{verbatim}CONFIG_ROM_IMAGE_SIZE\end{verbatim} + +Default image size. Defaults to \texttt{65535} bytes. + +\item \begin{verbatim}COREBOOT_EXTRA_VERSION\end{verbatim} + +coreboot extra version. This option has an empty string as default. Set +to any string to add an extra version string to your coreboot build. + +\end{itemize} + +\newpage + +\subsection{Mainboard specific configuration} + +Mainboard specific configuration files describe the onboard +mainboard components, i.e. bridges, number and type of CPUs. They also +contain rules for building the low level start code which is translated +using romcc and/or the GNU assembler. This code enables caches and +registers, early mtrr settings, fallback mechanisms, dram init and +possibly more. + +\textbf{NOTE:} The \texttt{option} keyword can not be used in mainboard +specific configuration files. Options shall instead be set using the +\texttt{default} keyword so that they can be overridden by the image +specific configuration files if needed. + +\subsubsection{Mainboard specific keywords} + +The following statements are used in mainboard specific configuration +files: + +\begin{itemize} +\item \begin{verbatim}arch\end{verbatim} + +Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.\\ +Example: + +\begin{verbatim} + arch i386 end +\end{verbatim} + +\item \begin{verbatim}cpu\end{verbatim} + +The cpu statement is needed once per possibly available CPU. In a +one-node system, write: + +\begin{verbatim} + cpu k8 "cpu0" end +\end{verbatim} + +\item \begin{verbatim}driver\end{verbatim} + +The \texttt{driver} keyword adds an object file to the driver section of a +coreboot image. This means it can be used by the PCI device +initialization code. Example: + +\begin{verbatim} + driver mainboard.o +\end{verbatim} + +\item \begin{verbatim}object\end{verbatim} + +The \texttt{object} keyword adds an object file to the coreboot image. +Per default the object file will be compiled from a \texttt{.c} file +with the same name. Symbols defined in such an object file can be used +in other object files and drivers. Example: + +\begin{verbatim} + object reset.o +\end{verbatim} + +\item \begin{verbatim}makerule\end{verbatim} + +This keyword can be used to extend the existing file creation rules +during the build process. This is useful if external utilities have to +be used for the build. coreboot on AMD64 uses romcc for it's early +startup code placed in auto.c. + +To tell the configuration mechanism how to build \texttt{romcc} files, +do: + +\begin{verbatim} +makerule ./auto.E + depends "$(CONFIG_MAINBOARD)/auto.c option_table.h ./romcc" + action "./romcc -E -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ + $(CONFIG_MAINBOARD)/auto.c -o $@" +end +makerule ./auto.inc + depends "$(CONFIG_MAINBOARD)/auto.c option_table.h ./romcc" + action "./romcc -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ + $(CONFIG_MAINBOARD)/auto.c -o $@" +end +\end{verbatim} + +Each \texttt{makerule} section contains file dependencies (using the +texttt{depends} keyword) and an action that is taken when the dependencies +are satisfied (using the \texttt{action} keyword). + +\item \begin{verbatim}mainboardinit\end{verbatim} + +With the mainboardinit keyword it's possible to include assembler code +directly into the coreboot image. This is used for early infrastructure +initialization, i.e. to switch to protected mode. Example: + +\begin{verbatim} + mainboardinit cpu/i386/entry16.inc +\end{verbatim} + +\item \begin{verbatim}ldscript\end{verbatim} + +The GNU linker ld is used to link object files together to a coreboot +ROM image. + +Since it is a lot more comfortable and flexible to use the GNU linker +with linker scripts (ldscripts) than to create complex command line +calls, coreboot features including linker scripts to control image +creation. Example: + +\begin{verbatim} + ldscript /cpu/i386/entry16.lds +\end{verbatim} + + +\item \begin{verbatim}dir\end{verbatim} + +coreboot reuses as much code between the different ports as possible. +To achieve this, commonly used code can be stored in a separate +directory. For a new mainboard, it is enough to know that the code in +that directory can be used as is. + +coreboot will also read a \texttt{Config.lb} file stored in that +directory. This happens with: + +\begin{verbatim} + dir /pc80 +\end{verbatim} + + +\item \begin{verbatim}config\end{verbatim} + +This keyword is needed by the new chip configuration scheme. Should be +used as: + +\begin{verbatim} + config chip.h +\end{verbatim} + +\item \begin{verbatim}register\end{verbatim} +The \texttt{register} keyword can occur in any section, passing +additional \\ +parameters to the code handling the associated device. +Example: + +\begin{verbatim} + register "com1" = "{1, 0, 0x3f8, 4}" +\end{verbatim} + +\item \begin{verbatim}northbridge\end{verbatim} + +The \texttt{northbridge} keyword describes a system northbridge. Some +systems, like AMD64, can have more than one northbridge, i.e. one per +CPU node. Each northbridge is described by the path to the northbridge +code in coreboot (relative to \texttt{coreboot-v2/src/northbridge}), i.e. +\texttt{amd/amdk8} and a unique name (i.e \texttt{mc0}) \\ +Example: + +\begin{verbatim} + northbridge amd/amdk8 "mc0" + [..] + end +\end{verbatim} + +\item \begin{verbatim}southbridge\end{verbatim} + +To simplify the handling of bus bridges in a coreboot system, all +bridges available in a system that are not northbridges (i.e AGP, IO, +PCIX) are seen as southbridges. + +Since from the CPUs point of view any southbridge is connected via the +northbridge, a southbridge section is declared within the northbridge +section of the north bridge it is attached to. + +Like the northbridge, any other bridge is described by the path to it's +driver code, and a unique name. If the described bridge is a +hypertransport device, the northbridge's hypertransport link it connects +to can be specified using the \texttt{link} keyword. Example: + +\begin{verbatim} +northbridge amd/amdk8 "mc0" + [..] + southbridge amd/amd8111 "amd8111" link 0 + [..] + end + [..] +end +\end{verbatim} + +\item \begin{verbatim}pci\end{verbatim} + +The \texttt{pci} keyword can only occur within a \texttt{northbridge} or +\texttt{southbridge} section. It is used to describe the PCI devices +that are provided by the bridge. Generally all bridge sections have a +couple of \texttt{pci} keywords. + +The first occurrence of the \texttt{pci} keyword tells coreboot where +the bridge devices start, relative to the PCI configuration space used +by the bridge. The following occurences of the \texttt{pci} keyword +describe the provided devices. + +Adding the option \texttt{on} or \texttt{off} to a PCI device will +enable or disable this device. This feature can be used if some bridge +devices are not wired to hardware outputs and thus are not used. + +Example: + +\begin{verbatim} +northbridge amd/amdk8 "mc1" + pci 0:19.0 + pci 0:19.0 + pci 0:19.0 + pci 0:19.1 + pci 0:19.2 + pci 0:19.3 +end +\end{verbatim} + +or + +\begin{verbatim} +southbridge amd/amd8111 "amd8111" link 0 + pci 0:0.0 + pci 0:1.0 on + pci 0:1.1 on + pci 0:1.2 on + pci 0:1.3 on + pci 0:1.5 off + pci 0:1.6 off + pci 1:0.0 on + pci 1:0.1 on + pci 1:0.2 on + pci 1:1.0 off + [..] +end +\end{verbatim} + +\item \begin{verbatim}superio\end{verbatim} + +SuperIO devices are basically handled like brigdes. They are taking +their driver code from \texttt{coreboot-v2/src/superio/}. They don't +provide a PCI compatible configuration interface, but instead are ISA +PnP devices. Normally they are connected to a southbridge. If this is +the case, the \texttt{superio} section will be a subsection of the +\texttt{southbridge} section of the southbridge it is connected to. +Example: + +\begin{verbatim} +superio nsc/pc87360 link 1 + pnp 2e.0 + pnp 2e.1 + pnp 2e.2 + pnp 2e.3 + pnp 2e.4 + pnp 2e.5 + pnp 2e.6 + pnp 2e.7 + pnp 2e.8 + pnp 2e.9 + pnp 2e.a + register "com1" = "{1, 0, 0x3f8, 4}" + register "lpt" = "{1}" +end +\end{verbatim} + +\end{itemize} + +\newpage + +\subsubsection{Mainboard specific configuration options} + +The following options are commonly used in mainboard specific +configuration files. + +They should be set using the \texttt{default} keyword: + +\begin{itemize} + +\item \begin{verbatim}CONFIG_HAVE_HARD_RESET\end{verbatim} + +If set to \texttt{1}, this option defines that there is a hard reset +function for this mainboard. This option is not defined per default. + +\item \begin{verbatim}CONFIG_HAVE_PIRQ_TABLE\end{verbatim} + +If set to \texttt{1}, this option defines that there is an IRQ Table for +this mainboard. This option is not defined per default. + +\item \begin{verbatim}CONFIG_IRQ_SLOT_COUNT\end{verbatim} + +Number of IRQ slots. This option is not defined per default. + +\item \begin{verbatim}CONFIG_HAVE_MP_TABLE\end{verbatim} + +Define this option to build an MP table (v1.4). The default is not to +build an MP table. + +\item \begin{verbatim}CONFIG_HAVE_OPTION_TABLE\end{verbatim} + +Define this option to export a CMOS option table. The default is not to +export a CMOS option table. + +\item \begin{verbatim}CONFIG_SMP\end{verbatim} + +Set this option to \texttt{1} if the mainboard supports symmetric +multiprocessing (SMP). This option defaults to \texttt{0} (no SMP). + +\item \begin{verbatim}CONFIG_MAX_CPUS\end{verbatim} + +If \begin{verbatim}CONFIG_SMP\end{verbatim} is set, this option defines +the maximum number of CPUs (i.e. the number of CPU sockets) in the +system. Defaults to \texttt{1}. + +\item \begin{verbatim}CONFIG_IOAPIC\end{verbatim} + +Set this option to \texttt{1} to enable IOAPIC support. This is +mandatory if you want to boot a 64bit Linux kernel on an AMD64 system. + +\item \begin{verbatim}CONFIG_STACK_SIZE\end{verbatim} + +coreboot stack size. The size of the function call stack defaults to +\texttt{0x2000} (8k). + +\item \begin{verbatim}CONFIG_HEAP_SIZE\end{verbatim} + +coreboot heap size. The heap is used when coreboot allocates memory +with malloc(). The default heap size is \texttt{0x2000}, but AMD64 boards +generally set it to \texttt{0x4000} (16k) + +\item \begin{verbatim}CONFIG_XIP_ROM_BASE\end{verbatim} + +Start address of area to cache during coreboot execution directly from +ROM. + +\item \begin{verbatim}CONFIG_XIP_ROM_SIZE\end{verbatim} + +Size of area to cache during coreboot execution directly from ROM + +\item \begin{verbatim}CONFIG_COMPRESS\end{verbatim} + +Set this option to \texttt{1} for a compressed image. If set to +\texttt{0}, the image is bigger but will start slightly faster (since no +decompression is needed). + +\end{itemize} + + +\newpage + +% +% 10. Tweaking the source code +% + +\section{Tweaking the source code} +Besides configuring the existing code it is sometimes necessary or +desirable to tweak certain parts of coreboot by direct changes to the +code. This chapter covers some possible enhancements and changes that +are needed when porting coreboot to a new mainboard or just come +handy now and then. + +\subsection{Hypertransport configuration} +Before coreboot is able to activate all CPUs and detect bridges +attached to these CPUs (and thus, see all devices attached to the +system) it has to initialize the coherent hypertransport devices. + +The current algorithms to do coherent hypertransport initialization are +not fully, automatically evaluating the hypertransport chain graph. +Therefore the code needs to be adapted when porting coreboot to a new +AMD64 mainboard. An example arrangement of hypertransport devices +looks like this: + +\begin{figure}[htb] +\centering +\includegraphics[scale=1.0]{hypertransport.pdf} +\caption{Example: Hypertransport Link Connections} +\label{fix:hypertransport} +\end{figure} + +Each hypertransport device has one to three hypertransport links that +are used for device interconnection. These links are called LDT$[$012$]$, or +accordingly UP, ACROSS, DOWN. Communication between the hypertransport +devices can be freely routed, honoring the physical wiring. Teaching the +coherent hypertransport initialization algorithm this wiring happens in +two steps. + +\newpage + +\begin{enumerate} +\item Setting outgoing connections +The algorithm needs to know which outgoing port of a CPU node is +connected to the directly succeeding node. This is done in +\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/auto.c} +with a number of preprocessor defines (one define for two-node systems, +three defines for four-node systems). + +The ports in question are flagged with a circle in the graph for +illustration. For the example graph above (all outgoing connections are +realized using LDT1/ACROSS) the defines are: + +\begin{verbatim} +#define CONNECTION_0_1 ACROSS +#define CONNECTION_0_2 ACROSS +#define CONNECTION_1_3 ACROSS +\end{verbatim} + +\item Describing routing information between CPUs. + +There are basically three different message types for hypertransport +communication: +\begin{enumerate} +\item request packages +\item response packages +\item broadcast packages +\end{enumerate} + +These three message types are routed using different hypertransport +ports. The routing information is written to the AMD K8 routing table. +In an Nnode system this routing table consists of 3*N*N entries , one +for each message type and for each possible CPU --> CPU communication. For +simplicity coreboot keeps the 3 routing entries for each CPU --> CPU +communication in one machine word. The routing table of each node looks +like this: + +\begin{verbatim} +/* Routing Table for Node i + * + * F0: 0x40, 0x44, 0x48, 0x4c, 0x50, 0x54, 0x58, 0x5c + * i: 0, 1, 2, 3, 4, 5, 6, 7 + * + * [ 0: 3] Request Route + * [0] Route to this node + * [1] Route to Link 0 + * [2] Route to Link 1 + * [3] Route to Link 2 + * [11: 8] Response Route + * [0] Route to this node + * [1] Route to Link 0 + * [2] Route to Link 1 + * [3] Route to Link 2 + * [19:16] Broadcast route + * [0] Route to this node + * [1] Route to Link 0 + * [2] Route to Link 1 + * [3] Route to Link 2 + */ +\end{verbatim} + +The routing table is passed to the coherent hypertransport +initialization algorithm by defining a function called +\texttt{generate\_row()} in \texttt{auto.c}: + +\begin{verbatim} +static unsigned int generate_row + (uint8_t node, uint8_t row, uint8_t maxnodes) +\end{verbatim} + +This function is trivial if there is only one CPU in the system, since +no routing has to be done: + +\begin{verbatim} +static unsigned int generate_row + (uint8_t node, uint8_t row, uint8_t maxnodes) +{ + return 0x00010101; /* default row entry */ +} +\end{verbatim} + +On a two-node system things look slightly more complicated. Since the +coherent hypertransport initialization algorithm works by consecutively +enabling CPUs, it contains routing information for driving the system +with one node and two nodes: + +\begin{verbatim} +static unsigned int generate_row + (uint8_t node, uint8_t row, uint8_t maxnodes) +{ + uint32_t ret=0x00010101; /* default row entry */ + static const unsigned int rows_2p[2][2] = { + { 0x00050101, 0x00010404 }, + { 0x00010404, 0x00050101 } + }; + if(maxnodes>2) maxnodes=2; + if (!(node>=maxnodes || row>=maxnodes)) { + ret=rows_2p[node][row]; + } + return ret; +} +\end{verbatim} + +Systems with four nodes have to contain routing information for one, two +and four-node setups: + +\begin{verbatim} +static unsigned int generate_row + (uint8_t node, uint8_t row, uint8_t maxnodes) +{ + uint32_t ret=0x00010101; /* default row entry */ + static const unsigned int rows_2p[2][2] = { + { 0x00030101, 0x00010202 }, + { 0x00010202, 0x00030101 } + }; + static const unsigned int rows_4p[4][4] = { + { 0x00070101, 0x00010202, 0x00030404, 0x00010204 }, + { 0x00010202, 0x000b0101, 0x00010208, 0x00030808 }, + { 0x00030808, 0x00010208, 0x000b0101, 0x00010202 }, + { 0x00010204, 0x00030404, 0x00010202, 0x00070101 } + }; + if (!(node>=maxnodes || row>=maxnodes)) { + if (maxnodes==2) + ret=rows_2p[node][row]; + if (maxnodes==4) + ret=rows_4p[node][row]; + } + return ret; +} +\end{verbatim} +\end{enumerate} + +\subsection{DRAM configuration} +Setting up the RAM controller(s) is probably the most complex part of +coreboot. Basically coreboot serially initializes all RAM controllers +in the system, using SPDROM (serial presence detect) data to set +timings, size and other properties. The SPD data is usually read +utilizing the I2C SMBUS interface of the southbridge. + +There is one central data structure that describes the RAM controllers +available on an AMD64 system and the associated devices: + +\begin{verbatim} +struct mem_controller { + unsigned node_id; + device_t f0, f1, f2, f3; + uint8_t channel0[4]; + uint8_t channel1[4]; +}; +\end{verbatim} + +Available mainboard implementations and CPUs create the need to add +special setup code to RAM initialization in a number of places. +coreboot provides hooks to easily add code in these places without +having to change the generic code. Whether these hooks have to be used +depends on the mainboard design. In many cases the functions executed +by the hooks just carry out trivial default settings or they are even +empty. + +Some mainboard/CPU combinations need to trigger an additional memory +controller reset before the memory can be initialized properly. This is, +for example, used to get memory working on preC stepping AMD64 +processors. coreboot provides two hooks for triggering onboard memory +reset logic: + +\begin{itemize} +\item \begin{verbatim}static void memreset_setup(void)\end{verbatim} +\item \begin{verbatim}static void memreset(int controllers, const struct + mem_controller *ctrl)\end{verbatim} +\end{itemize} + +Some mainboards utilize an SMBUS hub or possibly other mechanisms to +allow using a large number of SPDROMs and thus ram sockets. The result +is that only the SPDROM information of one cpu node is visible at a +time. The following function, defined in \texttt{auto.c}, is called every time +before a memory controller is initialized and gets the memory controller +information of the next controller as a parameter: + +\begin{verbatim} +static inline void activate_spd_rom (const struct mem_controller *ctrl) +\end{verbatim} + +The way SMBUS hub information is coded into the \texttt{mem\_controller} +structure is mainboard implementation specific and not +described here. See \texttt{coreboot-v2/src/mainboard/amd/quartet/auto.c} +for an example. + +coreboot folks have agreed on SPD data being the central information +source for RAM specific information. But not all mainboards/RAM +modules feature a physical SPD ROM. To still allow an easy to use SPD +driven setup, there is a hook that abstracts reading the SPD ROM +ingredients that are used by the memory initialization mechanism: + +\begin{verbatim} +static inline int spd_read_byte(unsigned device, unsigned address) +\end{verbatim} + +This function, defined in \texttt{auto.c}, directly maps it's calls to +\texttt{smbus\_read\_byte()} calls if SPD ROM information is read via +the I2C SMBUS: + +\begin{verbatim} +static inline int spd_read_byte(unsigned device, unsigned address) +{ + return smbus_read_byte(device & 0xff, address); +} +\end{verbatim} + +If there is no SPD ROM available in the system design, this function +keeps an array of SPD ROM information hard coded per logical RAM module. +It returns the faked' SPD ROM information using device and address +as indices to this array. + + +\subsection {IRQ Tables} + +Mainboards that provide an IRQ table should have the following two +variables set in their \texttt{Config.lb} file: + +\begin{verbatim} +default CONFIG_HAVE_PIRQ_TABLE=1 +default CONFIG_IRQ_SLOT_COUNT=7 +\end{verbatim} + +This will make coreboot look for the file \\ +\texttt{coreboot-v2/src/mainboard/<vendor>/<mainboard>/irq\_tables.c} which +contains the source code definition of the IRQ table. coreboot corrects +small inconsistencies in the IRQ table during startup (checksum and +number of entries), but it is not yet writing IRQ tables in a completely +dynamic way. + +\textbf{NOTE:} To get Linux to understand and actually use the IRQ +table, it is not always a good idea to specify the vendor and device id +of the actually present interrupt router device. Linux 2.4 for example +does not know about the interrupt router of the AMD8111 southbridge. In +such cases it is advised to choose the vendor/device id of a compatible +device that is supported by the Linux kernel. In case of the AMD8111 +interrupt router it is advised to specify the AMD768/Opus interrupt +controller instead (vendor id=\texttt{0x1022}, device id=\texttt{0x7443}) + +\subsection {MP Tables} + +coreboot contains code to create MP tables conforming the +Multiprocessor Specification V1.4. To include an MP Table in a coreboot +image, the following configuration variables have to be set (in the +mainboard specific configuration file +\texttt{coreboot-v2/src/mainboard/<vendor><mainboard>/Config.lb}): + +\begin{verbatim} +default CONFIG_SMP=1 +default CONFIG_MAX_CPUS=1 # 2,4,.. +default CONFIG_HAVE_MP_TABLE=1 +\end{verbatim} + +coreboot will then look for a function for setting up the MP table in +the file \texttt{coreboot-v2/src/mainboard<vendor>/<mainboard>/mptable.c}: + +\begin{verbatim} +void *smp_write_config_table(void *v, unsigned long * processor_map) +\end{verbatim} + +MP Table generation is still somewhat static, i.e. changing the bus +numbering will force +you to adopt the code in mptable.c. This is subject to change in future +revisions. + +\subsection {ACPI Tables} + +There is initial ACPI support in coreboot now. Currently the only gain with +this is the ability to use HPET timers in Linux. To achieve this, there is a +framework that can generate the following tables: +\begin{itemize} +\item RSDP +\item RSDT +\item MADT +\item HPET +\end{itemize} + +To enable ACPI in your coreboot build, add the following lines to your +configuration files: +\begin{verbatim} +uses CONFIG_HAVE_ACPI_TABLES +[..] +option CONFIG_HAVE_ACPI_TABLES=1 +\end{verbatim} + +To keep Linux doing it's pci ressource allocation based on IRQ tables and MP +tables, you have to specify the kernel parameter \texttt{pci=noacpi} otherwise +your PCI devices won't get interrupts. +It's likely that more ACPI support will follow, when there is need for certain +features. + +\subsection{POST} +coreboot has three different methods of handling POST codes. They can +be triggered using configuration file options. +\begin{itemize} +\item +\emph{Ignore POST completely}. No early code debugging is possible with +this setting. Set the configuration variable \texttt{NO\_POST} to +\texttt{1} to switch off all POST handling in coreboot. +\item +\emph{Normal IO port 80 POST}. This is the default behavior of +coreboot. No configuration variables have to be set. To be able to see +port 80 POST output, you need a POST expansion card for ISA or PCI. Port +80 POST allows simple debugging without any other output method +available (serial interface or VGA display) +\item +\emph{Serial POST}. +This option allows to push POST messages to the serial interface instead +of using IO ports. \textbf{NOTE:} The serial interface has to be +initialized before serial POST can work. To use serial POST, set the +configuration variable \texttt{CONFIG\_SERIAL\_POST} to the value 1. +\end{itemize} + + +\subsection{HDT Debugging} +If you are debugging your coreboot code with a Hardware Debug Tool +(HDT), you can find the source code line for a given physical EIP +address as follows: Look the address up in the file linuxbios.map. Then +search the label Lxx in the file auto.inc created by romcc. The original +source code file and line number is mentioned in auto.inc. + + +\subsection{Device Drivers} +With only a few data structures coreboot features a simple but flexible +device driver interface. This interface is not intended for autonomously +driving the devices but to initialize all system components so that they +can be used by the booted operating system. + +Since nowadays most systems are PCI centric, the data structures used +are tuned towards (onboard and expansion bus) PCI devices. Each driver +consists of at least two structures. + +The \texttt{pci\_driver} structure maps PCI vendor/device id pairs to a +second structure that describes a set of functions that together +initialize and operate the device: + +\begin{verbatim} + static void adaptec_scsi_init(struct device *dev) + { + [..] + } + static struct device_operations lsi_scsi_ops = { + .read_resources = pci_dev_read_resources, + .set_resources = pci_dev_set_resources, + .enable_resources = pci_dev_enable_resources, + .init = lsi_scsi_init, + .scan_bus = 0, + }; + static const struct pci_driver lsi_scsi_driver __pci_driver = { + .ops = &lsi_scsi_ops, + .vendor = 0xXXXX, + .device = 0xXXXX, + }; +\end{verbatim} + +By separating the two structures above, M:N relations between compatible +devices and drivers can be described. The driver source code containing +above data structures and code have to be added to a coreboot image +using the driver keyword in the mainboard specific configuration file \\ +\texttt{coreboot-v2/src/mainboard/<vendor>/<mainboard>/Config.lb}: + +\begin{verbatim} + driver lsi_scsi.o +\end{verbatim} + +\subsection{Bus Bridges} + +Currently all bridges supported in the coreboot-v2 tree are transparent +bridges. This means, once the bridge is initialized, it's remote devices +are visible on one of the PCI buses without special probing. coreboot +supports also bridges that are nontransparent. The driver support code +can provide a \texttt{scan\_bus} function to scan devices behind the bridge. + +\subsection{CPU Reset} +When changing speed and width of hypertransport chain connections +coreboot has to either assert an LDTSTOP or a reset to make the changes +become active. Additionally Linux can do a firmware reset, if coreboot +provides the needed infrastructure. To use this capability, define the +option \texttt{CONFIG\_HAVE\_HARD\_RESET} and add an object file specifying the +reset code in your mainboard specific configuration file +\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/Config.lb}: + +\begin{verbatim} + default CONFIG_HAVE_HARD_RESET=1 + object reset.o +\end{verbatim} + +The C source file \texttt{reset.c} (resulting in \texttt{reset.o} +during compilation) shall define the following function to take care +of the system reset: + +\begin{verbatim} + void hard_reset(void); +\end{verbatim} + +See \texttt{coreboot-v2/src/mainboard/arima/hdama/reset.c} for an example +implementation. + +\newpage + +% +% 11. coreboot Internals +% + +\section{coreboot Internals} +This chapter covers some of the internal structures and algorithms of +coreboot that have not been mentioned so far. + +\subsection{Code Flow} + +\begin{figure}[htb] +\centering +\includegraphics[scale=0.7]{codeflow.pdf} +\caption{coreboot rough Code Flow} +\label{fix:codeflow} +\end{figure} + +\newpage + +\subsection{Fallback mechanism} +coreboot provides a mechanism to pack two different coreboot builds +within one coreboot ROM image. Using the system CMOS memory coreboot +determines whether the last boot with a default image succeeded and +boots a failsafe image on failure. This allows insystem testing without +the risk to render the system unusable. See +\texttt{coreboot-v2/src/mainboard/arima/hdama/failover.c} for example +code. The fallback mechanism can be used with the \texttt{cmos\_util}. + +\subsection{(Un) Supported Standards} +coreboot supports the following standards +\begin{itemize} +\item Multiprocessing Specification (MPSPEC) 1.4 +\item IRQ Tables (PIRQ) +\item ACPI (initial support on AMD64) +\item Elf Booting +\end{itemize} +However, the following standards are not supported until now, and will +probably not be supported in future revisions: +\begin{itemize} +\item APM +\end{itemize} + +\subsection{coreboot table} +coreboot stores information about the system in a data structure called +the coreboot table. This table can be read under Linux using the tool +nvramtool from the Lawrence Livermore National Laboratory. + +Get more information about lxbios and the utility itself at +\url{http://www.llnl.gov/linux/lxbios/lxbios.html} + +\subsection{ROMCC limitations} +ROMCC, part of the coreboot project, is a C compiler that translates to +completely rommable code. This means the resulting code does not need +any memory to work. This is one of the major improvements in coreboot +V2, since it allows almost all code to be written in C. DRAM +initialization can be factored and reused more easily among mainboards +and platforms. + +Since no memory is available during this early initialization point, +romcc has to map all used variables in registers for the time being. +Same applies for their stack usage. Generally the less registers are +used up by the algorithms, the better code can be factored, resulting in +a smaller object size. Since getting the best register usage is an NP +hard problem, some heuristics are used to get reasonable translation +time. If you run out of registers during compilation, try to refactor +your code. + +\subsection{CMOS handling} +coreboot can use the mainboard's CMOS memory to store information +defined in a data structure called the CMOS table . This information +contains serial line speed, fallback boot control, output verbosity, +default boot device, ECC control, and more. It can be easily enhanced by +enhancing the CMOS table. This table, if present, is found at +\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/cmos.layout}. +It describes the available options, their possible values and their +position within the CMOS memory. The layout file looks as follows: +\begin{verbatim} + # startbit length config configID name + [..] + 392 3 e 5 baud_rate + [..] + + # configid value human readable description + 5 0 115200 + 5 1 57600 + 5 2 38400 + 5 3 19200 + 5 4 9600 + 5 5 4800 + 5 6 2400 + 5 7 1200 + +\end{verbatim} + +To change CMOS values from a running Linux system, use the +\texttt{cmos\_util}, provided by Linux Networks as part of the coreboot +utilities suite. Get it at +\textit{ftp://ftp.lnxi.com/pub/linuxbios/utilities/} + +\subsection {Booting Payloads} +coreboot can load a payload binary from a Flash device or IDE. This +payload can be a boot loader, like FILO or Etherboot, a kernel image, or +any other static ELF binary. If you specify a bzImage as the payload, +the cbfs utility will figure out how to create a coreboot payload from it. + +\subsection{Kernel on dhcp/tftp} + +One possible scenario during testing is that you keep your kernel (or +any additional payload) on a different machine on the network. This can +quickly be done using a DHCP and TFTP server. + +Use for example following \texttt{/etc/dhcpd.conf} (adapt to your +network): + +\begin{verbatim} + subnet 192.168.1.0 netmask 255.255.255.0 { + range 192.168.1.0 192.168.1.31; + option broadcastaddress 192.168.1.255; + } + + ddnsupdatestyle adhoc; + + host hammer12 { + hardware ethernet 00:04:76:EA:64:31; + fixedaddress 192.168.1.24; + filename "vmlinuz.elf"; + } +\end{verbatim} + + +Additionally you have to run a \texttt{tftp} server. You can start one +using \texttt{inetd}. To do this, you have to remove the comment from +the following line in \texttt{/etc/inetd.conf}: + +\begin{verbatim} + tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot +\end{verbatim} + +Then put your kernel image \texttt{vmlinuz.elf} in \texttt{/tftpboot} on +the \texttt{tftp} server. + + +\newpage + +% +% 12. Advanced Device Initialization Mechanisms +% + +\section{Advanced Device Initialization Mechanisms} + +Like software, today's hardware is getting more and more complex. To +stay flexible many hardware vendors start breaking hardware +compatibility to old standards like VGA. Thus, VGA is still supported by +most cards, but emulation has to be enabled by the firmware for the +device to operate properly. Also, many expansion cards are small +discrete systems that have to initialize attached ram, download +controller firmware and similar. Without this initialization, an +operating system can not take advantage of the hardware, so there needs +to be a way to address this issue. There are several alternatives: + +\subsection{Native coreboot Support} + +For some devices (ie Trident Cyberblade 3d) there is native coreboot +support This means there is a small driver bound to the PCI id of the +device that is called after PCI device ressources are allotted. + +PROs: + \begin{itemize} + \item open source + \item minimal driver + \item early control + \end{itemize} + +CONs: + \begin{itemize} + \item need an additional driver + \item viable for onboard devices only + \item not flexible for pci cards + \end{itemize} + +\subsection{Using Native Linux Support} + +A simple way of getting a whole lot of drivers available for coreboot +is to reuse Linux drivers by putting a Linux kernel to flash. This +works, because no drivers are needed to get the Linux kernel (as opposed +to store the kernel on a harddisk connected to isa/scsi/raid storage) + +PROs: + \begin{itemize} + \item large number of open source drivers + \end{itemize} + +CONs: + \begin{itemize} + \item need Linux in Flash (BLOAT!) + \item drivers expect devices to be initialized (LSI1020/1030) + \item Linux only + \item large flash needed (4MBit minimum, normal operations 8+ MBit) + \end{itemize} + + +\subsection{Running X86 Option ROMs} + +Especially SCSI/RAID controllers and graphics adapters come with a +special option rom. This option rom usually contains x86 binary code +that uses a legacy PCBIOS interface for device interaction. If this code +gets executed, the device becomes operable in Linux and other operating +systems. + +PROs: + \begin{itemize} + \item really flexible + \item no need for additional drivers on firmware layer + \item large number of supported devices + \end{itemize} + +CONs: + \begin{itemize} + \item non-x86 platforms need complex emulation + \item x86 platforms need legacy API + \item outdated concept + \end{itemize} + + +\subsection{Running Open Firmware Option ROMs} + +Some PCI devices come with open firmware option roms. These devices are +normally found in computers from SUN, Apple or IBM. Open Firmware is a +instruction set architecture independent firmware standard that allows +device specific initialization using simple, small, but flexible +bytecode that runs with minimal footprint on all architectures that have +an Open Firmware implementation. + +There is a free Open Firmware implementation available, called OpenBIOS, +that runs on top of coreboot. See www.openbios.org + +PROs: + \begin{itemize} + \item architecture independence + \item small footprint + \item clean concept, less bugs + \end{itemize} + +CONs: + \begin{itemize} + \item only small number of devices come with OpenFirmware capable option roms + \end{itemize} + +% +% 13 image types +% + +\section{Image types} +There used to be one image type for coreboot, as described above. Since this paper was written (2004) there have been many changes. First, the name +was changed to coreboot, for many reasons. Second, Cache As Ram support (CAR) +was added for many AMD CPUs, which both simplified and complicated things. Simplification came with the removal of romcc; complication came with the addition of new ways to build. + +There are two big additions to the build process and, furthermore, more than two new CONFIG variables to control them. + +\begin{itemize} +\item \begin{verbatim}CONFIG_USE_DCACHE_RAM\end{verbatim} + +Set to \texttt{1} to use Cache As Ram (CAR). Defaults to \texttt{0} + +\end{itemize} + +Before going over the new image types, derived from v3, we will quickly review the standard v2 image types. We are hoping this review will +aid comprehension. + +A coreboot rom file consists of one or more \textit{images}. All images consist of a part that runs in ROM, and a part that runs in RAM. The RAM can be in compressed form and is decompressed when needed by the ROM code. The main function of the ROM code is to get memory working. Both ROM and RAM consist of a very small amount of assembly code and mostly C code. + +\subsection{romcc images (from emulation/qemu)} +ROMCC images are so-called because C code for the ROM part is compiled with romcc. romcc is an optimizing C compiler which compiles one, and only +one file; to get more than one file, one must include the C code via include statements. The main ROM code .c file is usually called auto.c. +\subsubsection{How it is built} +Romcc compiles auto.c to produce auto.inc. auto.inc is included in the main crt0.S, which is then preprocessed to produce crt0.s. The inclusion of files into crt0.S is controlled by the CONFIG\_CRT0\_INCLUDES variable. crt0.s is then assembled. + +File for the ram part are compiled in a conventional manner. + +The final step is linking. The use of named sections is used very heavily in coreboot to control where different bits of code go. The reset vector must go in the top 16 bytes. The start portion of the ROM code must go in the top 64K bytes, since most chipsets only enable this much ROM at startup time. Here is a quick look at a typical image: +\begin{verbatim} + [Nr] Name Type Addr Off Size ES Flg Lk Inf Al + [ 0] NULL 00000000 000000 000000 00 0 0 0 + [ 1] .ram PROGBITS ffff0000 001000 005893 00 WA 0 0 1 + [ 2] .rom PROGBITS ffff5893 006893 00029d 00 AX 0 0 16 + [ 3] .reset PROGBITS fffffff0 006ff0 000010 00 A 0 0 1 + [ 4] .id PROGBITS ffffffd1 006fd1 00001f 00 A 0 0 1 + [ 5] .shstrtab STRTAB 00000000 007000 000030 00 0 0 1 + [ 6] .symtab SYMTAB 00000000 007170 000c30 10 7 37 4 + [ 7] .strtab STRTAB 00000000 007da0 000bfd 00 0 0 1 +\end{verbatim} + +The only sections that get loaded into a ROM are the Allocated ones. We can see the .ram, .rom, .reset and .id sections. +\subsubsection{layout} +As we mentioned, the ROM file consists of multiple images. In the basic file, there are two full coreboot rom images. The build sequence for each is the same, and in fact the ldscript.ld files are almost identical. The only difference is in a few makefile variables, generated by the config tool. + +\begin{itemize} +\item CONFIG\_PAYLOAD\_SIZE. Each image may have a different payload size. +\item CONFIG\_ROMBASE Each image must have a different base in rom. +\item CONFIG\_RESET Unclear what this is used for. +\item CONFIG\_EXCEPTION\_VECTORS where an optional IDT might go. +\item CONFIG\_USE\_OPTION\_TABLE if set, an option table section will be linked in. +\item CONFIG\_ROM\_PAYLOAD\_START This is the soon-to-be-deprecated way of locating a payload. cbfs eliminates this. +\item CONFIG\_USE\_FALLBACK\_IMAGE Whether this is a fallback or normal image +\item CONFIG\_ROM\_SECTION\_SIZE Essentially, the payload size. Soon to be deprecated. +\item CONFIG\_ROM\_IMAGE\_SIZE Size of this image (i.e. fallback or normal image) +\item CONFIG\_ROM\_SIZE Total size of the ROM +\item CONFIG\_XIP\_RAM\_BASE The start of eXecute In Place code. XIP allows for not copying code to ram, but just running it from ROM. +\end{itemize} + +Each image (normal or fallback) is built completely independently and does not get linked to the other. They are assembled into one ROM image by the (soon to be deprecated) buildrom tool, or by the cbfs tool. + +\subsubsection{boot sequence} +We boot and start at fffffff0. We then jump to the entry point at \_start. \_start does some machine init and an lgdt and jumps to \_\_protected\_start, at which point we are in protected mode. The code does a bit more machine setup and then starts executing the romcc code. + +If fallback has been built in, some setup needs to be done. On some machines, it is extensive. Full rom decoding must be enabled. This may in turn require additional PCI setup to enable decoding to be enabled (!). To decided which image to use, hardware registers (cold boot on the Opteron) or CMOS are checked. Finally, once the image to use has been decided, a jmp is performed, viz: +\begin{verbatim} + /* This is the primary cpu how should I boot? */ + else if (do_normal_boot()) { + goto normal_image; + } + else { + goto fallback_image; + } + normal_image: + __asm__ volatile ("jmp __normal_image" + : /* outputs */ + : "a" (bist), "b" (cpu_init_detectedx) /* inputs */ + ); + + fallback_image: +#if CONFIG_HAVE_FAILOVER_BOOT==1 + __asm__ volatile ("jmp __fallback_image" + : /* outputs */ + : "a" (bist), "b" (cpu_init_detectedx) /* inputs */ + ) +#endif + ; +\end{verbatim} +How does the fallback image get the symbol for normal entry? Via magic in the ldscript.ld -- remember, the images are not linked to each other. +Finally, we can see this in the Config.lb for most mainboards: +\begin{verbatim} +if CONFIG_USE_FALLBACK_IMAGE + mainboardinit cpu/x86/16bit/reset16.inc + ldscript /cpu/x86/16bit/reset16.lds +else + mainboardinit cpu/x86/32bit/reset32.inc + ldscript /cpu/x86/32bit/reset32.lds +end +\end{verbatim} +What does this mean? the non-fallback image has a 32-bit entry point; fallback has a 16-bit entry point. The reason for this is that some code from fallback always runs, so as to pick fallback or normal; but the normal is always called from 32-bit code. +\subsection{car images (from lippert/roadrunner-lx)} +CAR images in their simplest form are modified romcc images. The file is usually cache\_as\_ram\_auto.c. C inclusion is still used. The main difference is in the build sequence. The compiler command line is a very slight changed: instead of using romcc to generate an auto.inc include file, gcc us used. Then, two perl scripts are used to rename the .text and .data sections to .rom.text and .rom.data respectively. +\subsubsection{How it is built} +The build is almost identical to the romcc build. Since the auto.inc file exists, it can be included as before. The crt0\_includes.h file has one addition: a file that enables CAR, in this case it is \textit{src/cpu/amd/model\_lx/cache\_as\_ram.inc}. +\subsubsection{layout} +No significant change from romcc code. +\subsubsection{boot sequence} +No significant change from romcc code, except that the CAR code has to set up a stack. + +\subsection{car + CONFIG\_USE\_INIT images (new emulation/qemu} +This type of image makes more use of the C compiler. In this type of image, in fact, +seperate compilation is possible but is not always used. Oddly enough, this option is only used in PPC boards. That said, we need to move to this way of building. Including C code is poor style. +\subsubsection{How it is built} +There is a make variable, INIT-OBJECTS, that for all our other targets is empty. In this type of build, INIT-OBJECTS is a list of C files that are created from the config tool initobject command. Again, with INIT-OBJECTS we can finally stop including .c files and go with seperate compilation. +\subsubsection{layout} +No significant change from romcc code. +\subsubsection{boot sequence} +No significant change from romcc code, except that the CAR code has to set up a stack. + +\subsubsection{layout} +No significant change from romcc code. +\subsubsection{boot sequence} +No significant change from romcc code, except that the CAR code has to set up a stack. +\subsection{failover} +Failover is the newest way to lay out a ROM. The choice of which image to run is removed from the fallback image and moved into a small, standalone piece of code. The code is simple enough to show here: +\begin{verbatim} +static unsigned long main(unsigned long bist) +{ + if (do_normal_boot()) + goto normal_image; + else + goto fallback_image; + +normal_image: + __asm__ __volatile__("jmp __normal_image" : : "a" (bist) : ); + +cpu_reset: + __asm__ __volatile__("jmp __cpu_reset" : : "a" (bist) : ); + +fallback_image: + return bist; +} + +\end{verbatim} +Some motherboards have a more complex bus structure (e.g. Opteron). In those cases, the failover can be more complex, as it requires some hardware initialization to work correctly. As of this writing (April 2009), these boards have their own failover: +\begin{quote} +./src/mainboard/iei/nova4899r/failover.c +./src/mainboard/emulation/qemu-x86/failover.c +./src/mainboard/supermicro/x6dhr\_ig/failover.c +./src/mainboard/supermicro/x6dai\_g/failover.c +./src/mainboard/supermicro/x6dhe\_g2/failover.c +./src/mainboard/supermicro/x6dhr\_ig2/failover.c +./src/mainboard/supermicro/x6dhe\_g/failover.c +./src/mainboard/dell/s1850/failover.c +./src/mainboard/intel/xe7501devkit/failover.c +./src/mainboard/intel/jarrell/failover.c +./src/mainboard/olpc/btest/failover.c +./src/mainboard/olpc/rev\_a/failover.c +./src/mainboard/via/epia-m/failover.c +\end{quote} +Here is one of the more complicated ones: +\begin{verbatim} +static unsigned long main(unsigned long bist) +{ + /* Did just the cpu reset? */ + if (memory_initialized()) { + if (last_boot_normal()) { + goto normal_image; + } else { + goto cpu_reset; + } + } + + /* This is the primary cpu how should I boot? */ + else if (do_normal_boot()) { + goto normal_image; + } + else { + goto fallback_image; + } + normal_image: + asm volatile ("jmp __normal_image" + : /* outputs */ + : "a" (bist) /* inputs */ + : /* clobbers */ + ); + cpu_reset: + asm volatile ("jmp __cpu_reset" + : /* outputs */ + : "a"(bist) /* inputs */ + : /* clobbers */ + ); + fallback_image: + return bist; +} + +\end{verbatim} +They're not that different, in fact. So why are there different copies all over the tree? Simple: code inclusion. Most of the failover.c are different because they include different bits of code. Here is a key reason for killing C code inclusion in the tree. +\subsubsection{How it is built} +There two additional config variables: +\begin{itemize} +\item HAVE\_FAILOVER\_IMAGE Has to be defined when certain files are included. +\item USE\_FAILOVER\_IMAGE Enables the use of the failover image +\end{itemize} +Confusingly enough, almost all the uses of these two variables are either nested or both required to be set, e.g. +The fallback and normal builds are the same. The target config has a new clause that looks like this: +\begin{verbatim} +romimage "failover" + option CONFIG_USE_FAILOVER_IMAGE=1 + option CONFIG_USE_FALLBACK_IMAGE=0 + option CONFIG_ROM_IMAGE_SIZE=CONFIG_FAILOVER_SIZE + option CONFIG_XIP_ROM_SIZE=CONFIG_FAILOVER_SIZE + option COREBOOT_EXTRA_VERSION="\$(shell cat ../../VERSION)\_Failover" +end +\end{verbatim} +This new section uses some constructs not yet discussed in detail. XIP\_ROM\_SIZE just refers to the +fact that the failover code is eXecute In Place, i.e. not copied to RAM. Of course, the ROM part of normal/fallback is as well, so the usage of XIP here is somewhat confusing. Finally, the USE\_FAILOVER\_IMAGE variable is set, which changes code compilation in a few places. If we just consider non-mainbard files, there are: +\begin{verbatim} +src/cpu/amd/car/cache_as_ram.inc +src/arch/i386/Config.lb +\end{verbatim} +For the cache\_as\_ram.inc file, the changes relate to the fact that failover code sets up CAR, so that fallback code need not. + +For the Config.lb, several aspects of build change. +When USE\_FAILOVER\_IMAGE, entry into both normal and fallback bios images is via a 32-bit entry point (when not defined, entry into fallback is a 16-entry point at the power-on reset vector). +\subsubsection{layout} +Failover.c becomes the new bootblock at the top of memory. It calls either normal or fallback. The address of normal and fallback is determined by ldscript magic. +\subsubsection{boot sequence} +failover.c tests a few variables and the calls the normal or fallback payload depending on those variables; usually they are CMOS settings. +\subsection{Proposed new image forat} +The new image format will use seperate compilation -- no C code included! -- on all files. + +The new design has a few key goals: +\begin{itemize} +\item Always use a bootblock (currently called failover). +The name failover.c, being utterly obscure, will not be used; instead, we will name the file bootblock.c. Instead of having a different copy for each mainboard, we can have just one copy. +\item Always use seperate compilation +\item Always use printk etc. in the ROM code +\item (longer term) from the bootblock, always use cbfs to locate the normal/fallback etc. code. This code will be XIP. +\end{itemize} + +\subsubsection{How it is built} +For now, since we are still using the config tool, we'll need a new command: bootblockobject, which creates a list of files to be included in the bootblock. Not a lot else will have to change. We are going to move to using the v3 CAR code assembly code (one or two files at most, instead of many) and, instead of the thicket of little ldscript files, one ldscript file. This strategy is subject to modification as events dictate. +\subsubsection{layout} +Almost the same, for now, as the current failover code. +\subsubsection{boot sequence} +% +% 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. +\end{itemize} + +\newpage + +% +% 14 Bibliography +% + +\section{Bibliography} +\subsection{Additional Papers on coreboot} + +\begin{itemize} + \item + \textit{\url{http://www.coreboot.org/Documentation}} + \item + \textit{\url{http://www.lysator.liu.se/upplysning/fa/linuxbios.pdf}} + \item + \textit{\url{http://portal.acm.org/citation.cfm?id=512627}} +\end{itemize} + +\subsection {Links} + +\begin{itemize} + \item Etherboot: \textit{\url{http://www.etherboot.org/}} + \item Filo: \textit{\url{http://www.coreboot.org/FILO}} + \item OpenBIOS: \textit{\url{http://www.openbios.org/}} +\end{itemize} + +\end{document} diff --git a/Documentation/Doxyfile.coreboot b/Documentation/Doxyfile.coreboot new file mode 100644 index 0000000000..e6c06fe59c --- /dev/null +++ b/Documentation/Doxyfile.coreboot @@ -0,0 +1,1639 @@ +# 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 new file mode 100644 index 0000000000..2135d96b3b --- /dev/null +++ b/Documentation/Doxyfile.coreboot_simple @@ -0,0 +1,259 @@ +# 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 \ + documentation +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/Kconfig.tex b/Documentation/Kconfig.tex new file mode 100644 index 0000000000..2b2bf7f4fe --- /dev/null +++ b/Documentation/Kconfig.tex @@ -0,0 +1,480 @@ +\documentclass[10pt,letterpaper]{article} +\usepackage[latin1]{inputenc} +\usepackage{amsmath} +\usepackage{amsfonts} +\usepackage{amssymb} +\author{Ron Minnich} +\title{Kconfig usage in coreboot v2} +\begin{document} +\section{Introduction} +This document describes how to use Kconfig in v2. We describe our usage of Kconfig files, Makefile.inc files, when and where to use them, how to use them, and, interestingly, when and where not to use them. +\section{Kconfig variations} +Most Kconfig files set variables, which can be set as part of the Kconfig dialog. Not all Kconfig variables are set by the user, however; some are too dangerous. These are merely enabled by the mainboard. + +For variables set by the user, see src/console/Kconfig. + +For variables not set by the user, see src/mainboard/amd/serengeti\_cheetah/Kconfig. Users should never set such variables as the cache as ram base. These are highly mainboard dependent. + +Kconfig files use the source command to include subdirectories. In most cases, save for limited cases described below, subdirectories have Kconfig files. They are always sourced unconditionally. + +\section{Makefile and Makefile.inc} +There is only one Makefile, at the top level. All other makefiles are included as Makefile.inc. All the next-level Makefile.inc files are selected in the top level Makefile. Directories that are platform-independent are in BUILD-y; platform-dependent (e.g. Makefile.inc's that depend on architecture) are included in PLATFORM-y. + +Make is not recursive. There is only one make process. +\subsection{subdirs usage} +Further includes of Makefile.inc, if needed, are done via subdirs-y commands. As in Linux, the subdirs can be conditional or unconditional. Conditional includes are done via subdirs-\$(CONFIG\_VARIABLE) usage; unconditional are done via subdirs-y. + +We define the common rules for which variation to use below. +\subsection{object file specification} +There are several different types of objects specified in the tree. They are: +\begin{description} +\item[obj]objects for the ram part of the code +\item[driver]drivers for the ram part. Drivers are not represented in the device tree but do have a driver struct attached in the driver section. +\item[initobj]seperately-compiled code for the ROM section of coreboot +\end{description} +These items are specified via the -y syntax as well. Conditional object inclusion is done via the -\$(CONFIG\_VARIABLE) syntax. + +\section{Example: AMD serengeti cheetah} +\subsection{mainboard/Kconfig} +Defines Vendor variables. Currently defined variables are: +Sources all Kconfig files in the vendor directories. +\input{ mainboardkconfig.tex} +\subsection{mainboard/Makefile.inc} +There is none at this time. +\subsection{mainboard/$<$vendor$>$/Kconfig} +We use the amd as a model. The only action currently taken is to source all Kconfig's in the +subdirectories. +\subsection{mainboard/$<$vendor$>$/Makefile.inc} +We use amd as a model. There is currently no Makefile.inc at this level. +\subsection{mainboard/$<$vendor$>$/$<$board$>$/Kconfig} +The mainboard Kconfig and Makefile.inc are designed to be the heart of the build. The defines +and rules in here determine everything about how a mainboard target is built. +We will use serengeti\_cheetah as a model. It defines these variables. +\input{ mainboardkconfig.tex} +\subsection{mainboard/$<$vendor$>$/$<$board$>$/Makefile.inc} +This is a fairly complex Makefile.inc. Because this is such a critical component, we are going to excerpt and take it piece by piece. +Note that this is the mainboard as of August, 2009, and it may change over time. +\subsubsection{objects} +We define objects in the first part. The mainbard itself is a driver and included unconditionally. Other objects are conditional: +\begin{verbatim} +driver-y += mainboard.o + +#needed by irq_tables and mptable and acpi_tables +obj-y += get_bus_conf.o +obj-$(CONFIG_HAVE_MP_TABLE) += mptable.o +obj-$(CONFIG_HAVE_PIRQ_TABLE) += irq_tables.o +obj-$(CONFIG_HAVE_ACPI_TABLES) += dsdt.o +obj-$(CONFIG_HAVE_ACPI_TABLES) += acpi_tables.o +obj-$(CONFIG_HAVE_ACPI_TABLES) += fadt.o + +#./ssdt.o is in northbridge/amd/amdk8/Config.lb +obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt2.o +obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt3.o +obj-$(CONFIG_HAVE_ACPI_TABLES) += ssdt4.o +driver-y += ../../../drivers/i2c/i2cmux/i2cmux.o + +# This is part of the conversion to init-obj and away from included code. + +initobj-y += crt0.o +\end{verbatim} +\subsubsection{romcc legacy support} +We hope to move away from romcc soon, but for now, if one is using romcc, the Makefile.inc must define +crt0 include files (assembly code for startup, usually); and several ldscripts. These are taken directly from the +old Config.lb. Note that these use the -y syntax and can use the ability to be included conditionally. +\begin{verbatim} +crt0-y += ../../../../src/cpu/x86/16bit/entry16.inc +crt0-y += ../../../../src/cpu/x86/32bit/entry32.inc +crt0-y += ../../../../src/cpu/x86/16bit/reset16.inc +crt0-y += ../../../../src/arch/i386/lib/id.inc +crt0-y += ../../../../src/cpu/amd/car/cache_as_ram.inc +crt0-y += auto.inc + +ldscript-y += ../../../../src/arch/i386/init/ldscript_fallback_cbfs.lb +ldscript-y += ../../../../src/cpu/x86/16bit/entry16.lds +ldscript-y += ../../../../src/cpu/x86/16bit/reset16.lds +ldscript-y += ../../../../src/arch/i386/lib/id.lds +ldscript-y += ../../../../src/arch/i386/lib/failover.lds + +\end{verbatim} +\subsubsection{POST\_EVALUATION} +POST\_EVALUATION rules should be placed after this section: +\begin{verbatim} +ifdef POST_EVALUATION +\end{verbatim} +to ensure that the values of variables are correct. +Here are the post-evaluation rules for this mainboard: +\begin{verbatim} +$(obj)/dsdt.c: $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl + iasl -p dsdt -tc $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl + mv dsdt.hex $@ + +$(obj)/mainboard/$(MAINBOARDDIR)/dsdt.o: $(obj)/dsdt.c + $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c $< -o $@ + +$(obj)/ssdt2.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci2.asl + iasl -p $(CURDIR)/pci2 -tc $(CONFIG_MAINBOARD)/dx/pci2.asl + perl -pi -e 's/AmlCode/AmlCode_ssdt2/g' pci2.hex + mv pci2.hex ssdt2.c + +$(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl" + iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/ + perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex + mv pci3.hex ssdt3.c + +$(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl" + iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl + perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex + mv pci4.hex ssdt4.c + +$(obj)/mainboard/$(MAINBOARDDIR)/auto.inc: $(src)/mainboard/$(MAINBOARDDIR)/rom.c $(obj)/option_table.h + $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c -S $(src)/mainboard/$(MAINBOARDDIR)/rom.c -o $@ + perl -e 's/\.rodata/.rom.data/g' -pi $@ + perl -e 's/\.text/.section .rom.text/g' -pi $@ + +\end{verbatim} +The last rule is for romcc, and, again, we hope to eliminate romcc usage and this rule soon. The first set of rules concern ACPI tables. +\subsubsection{devicetree.cb} +Most of the old Config.lb is gone, but one piece remains: the device tree specification. This tree is still required to build a mainboard +properly, as it defines topology and chips that can be defined no other way. +Let's go through the tree. +\begin{verbatim} +chip northbridge/amd/amdk8/root_complex + device cpu_cluster 0 on + chip cpu/amd/socket_F + device lapic 0 on end + end + end +\end{verbatim} +This topology is always somewhat confusing to newcomers, and even to coreboot veterans. + +We root the tree at the pci-e {\it root complex}. There is always the question of how and where to root the tree. Over the years we +have found that the one part that never goes away is the root complex. CPU sockets may be empty or full; but there is always a northbridge +somewhere, since it runs memory. + + +What is the APIC? Northbridges always have an Advanced Programmable Interrupt Controller, and that {\it APIC cluster} is a topological connection to the +CPU socket. So the tree is rooted at the northbridge, which has a link to a CPU cluster, and then the CPU. The CPU contains +its own APIC, and will define any parameters needed. In this case, we have a northbridge of type +{\it northbridge/amd/amdk8/root\_complex}, with its own cpu\_cluster device which we turn on, +which connects to a {\it cpu/amd/socket\_F}, +which has a local apic, which is on. + +Note that we do not enumerate all CPUs, even on this SMP mainboard. The reason is they may not all be there. The CPU we define here +is the so-called Boot Strap Processor, or BSP; the other CPUs will come along later, as the are discovered. We do not require (unlike many +BIOSes) that the BSP be CPU 0; any CPU will do. +\begin{verbatim} + device domain 0 on + chip northbridge/amd/amdk8 + device pci 18.0 on # northbridge + # devices on link 0, link 0 == LDT 0 +\end{verbatim} +Here begins the pci domain, which usually starts with 0. Then there is the northbridge, which bridges to the PCI bus. On +Opterons, certain CPU control registers are managed in PCI config space in device 18.0 (BSP), 19.0 (AP), and up. +\begin{verbatim} + chip southbridge/amd/amd8132 + # the on/off keyword is mandatory + device pci 0.0 on end + device pci 0.1 on end + device pci 1.0 on end + device pci 1.1 on end + end +\end{verbatim} +This is the 8132, a bridge to a secondary PCI bus. +\begin{verbatim} + chip southbridge/amd/amd8111 + # this "device pci 0.0" is the parent the next one + # PCI bridge + device pci 0.0 on + device pci 0.0 on end + device pci 0.1 on end + device pci 0.2 off end + device pci 1.0 off end + end +\end{verbatim} +The 8111 is a bridge to other busses and to the legacy ISA devices such as superio. +\begin{verbatim} + device pci 1.0 on + chip superio/winbond/w83627hf + device pnp 2e.0 off # Floppy + io 0x60 = 0x3f0 + irq 0x70 = 6 + drq 0x74 = 2 + end + device pnp 2e.1 off # Parallel Port + io 0x60 = 0x378 + irq 0x70 = 7 + end + device pnp 2e.2 on # Com1 + io 0x60 = 0x3f8 + irq 0x70 = 4 + end + device pnp 2e.3 off # Com2 + io 0x60 = 0x2f8 + irq 0x70 = 3 + end + device pnp 2e.5 on # Keyboard + io 0x60 = 0x60 + io 0x62 = 0x64 + irq 0x70 = 1 + irq 0x72 = 12 + end + device pnp 2e.6 off # CIR + io 0x60 = 0x100 + end + device pnp 2e.7 off # GAME_MIDI_GIPO1 + io 0x60 = 0x220 + io 0x62 = 0x300 + irq 0x70 = 9 + end + device pnp 2e.8 off end # GPIO2 + device pnp 2e.9 off end # GPIO3 + device pnp 2e.a off end # ACPI + device pnp 2e.b on # HW Monitor + io 0x60 = 0x290 + irq 0x70 = 5 + end + end + end +\end{verbatim} +The pnp refers to the many Plug N Play devices on a superio. 2e refers to the base I/O address of the superio, and the number following the +2e (i.e. 2e.1) is the Logical Device Number, or LDN. Each LDN has a common configuration (base, irq, etc.) and these are set by the statements under the LDN. +\begin{verbatim} + device pci 1.1 on end + device pci 1.2 on end +\end{verbatim} +More devices. These statements set up placeholders in the device tree. +\begin{verbatim} + device pci 1.3 on + chip drivers/i2c/i2cmux # pca9556 smbus mux + device i2c 18 on #0 pca9516 1 + chip drivers/generic/generic #dimm 0-0-0 + device i2c 50 on end + end + chip drivers/generic/generic #dimm 0-0-1 + device i2c 51 on end + end + chip drivers/generic/generic #dimm 0-1-0 + device i2c 52 on end + end + chip drivers/generic/generic #dimm 0-1-1 + device i2c 53 on end + end + end + device i2c 18 on #1 pca9516 2 + chip drivers/generic/generic #dimm 1-0-0 + device i2c 50 on end + end + chip drivers/generic/generic #dimm 1-0-1 + device i2c 51 on end + end + chip drivers/generic/generic #dimm 1-1-0 + device i2c 52 on end + end + chip drivers/generic/generic #dimm 1-1-1 + device i2c 53 on end + end + chip drivers/generic/generic #dimm 1-2-0 + device i2c 54 on end + end + chip drivers/generic/generic #dimm 1-2-1 + device i2c 55 on end + end + chip drivers/generic/generic #dimm 1-3-0 + device i2c 56 on end + end + chip drivers/generic/generic #dimm 1-3-1 + device i2c 57 on end + end + end + end + end # acpi +\end{verbatim} +These are the i2c devices. +\begin{verbatim} + device pci 1.5 off end + device pci 1.6 off end +\end{verbatim} +More placeholders. +\begin{verbatim} + register "ide0_enable" = "1" + register "ide1_enable" = "1" + end + end # device pci 18.0 + +\end{verbatim} +These "register" commands set controls in the southbridge. +\begin{verbatim} + device pci 18.0 on end + device pci 18.0 on end +\end{verbatim} +These are the other two hypertransport links. +\begin{verbatim} + device pci 18.1 on end + device pci 18.2 on end + device pci 18.3 on end +\end{verbatim} +The 18.1 devices are, again, northbridge control for various k8 functions. +\begin{verbatim} + end + \end{verbatim} +That's it for the BSP I/O and HT busses. Now we begin the AP busses. Not much here. +\begin{verbatim} + chip northbridge/amd/amdk8 + device pci 19.0 on # northbridge + chip southbridge/amd/amd8151 + # the on/off keyword is mandatory + device pci 0.0 on end + device pci 1.0 on end + end + end # device pci 19.0 + + device pci 19.0 on end + device pci 19.0 on end + device pci 19.1 on end + device pci 19.2 on end + device pci 19.3 on end + end + + +\end{verbatim} + +\subsection{cpu socket} +The CPU socket is the key link from mainboard to its CPUs. Since many models of CPU can go in a socket, the mainboard mentions only +the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus +of all defines and Makefile controls for building the CPU components of a board. + +\subsubsection{ cpu/Kconfig} +Defines variables. Current variables are: +\input{cpukconfig.tex} +Sources all Kconfig files in the vendor directories. +\subsubsection{ cpu/Makefile.inc} +Unconditionally sources all Makefile.inc in the vendor directories. + +\subsection{cpu/$<$vendor$>$/Kconfig} +The only action currently taken is to source all Kconfig's in the +subdirectories. +\subsection{cpu/$<$vendor$>$/Makefile.inc} +{\em Conditionally} source the socket directories. +Example: +\begin{verbatim} +subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F +\end{verbatim} +. +CONFIG\_CPU\_AMD\_SOCKET\_F is set in a mainboard file. + +\subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig} +Set variables that relate to this {\em socket}, and {\em any models that plug into this socket}. Note that +the socket, as much as possible, should control the models, because the models may plug into many sockets. +Socket\_F currently sets: +\input{socketfkconfig.tex} + +It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced. + +\subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig} +CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that +if needed. +\subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc} +The Makefile.inc {\em unconditionally} specifies drivers and objects to be included in the build. There is no conditional +compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include {em all} +objects, because it is not possible to determine at build time what options may be needed for a given model CPU. +This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc. + +\subsection{northbridge} +\subsubsection{northbridge/Kconfig} +No variables. Source all vendor directory Kconfigs. +\subsubsection{northbridge/Makefile.inc} +No variables. unconditionally include all vendor Makefile.inc +\subsubsection{northbridge/$<$vendor$>$/Kconfig} +No variables. Source all chip directory Kconfigs. +\subsubsection{northbridge/$<$vendor$>$/Makefile.inc} +No variables. {\em Conditionally} include all chipset Makefile.inc. The variable +is the name of the part, e.g. +\begin{verbatim} +subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8 +\end{verbatim} +. +\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig} +Typically a small number of variables. One defines the part name. Here is an example +of the variables defined for the K8. +\begin{verbatim} +config NORTHBRIDGE_AMD_AMDK8 + bool + default n + +config AGP_APERTURE_SIZE + hex + default 0x4000000 +\end{verbatim} +\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc} +Typically very small set of rules, and very simple. +Since this file is already conditionally included, +we don't need to test for the chipset CONFIG variable. We +can therefore test other variables (which is part of the reason +we set up conditional inclusion of this file, instead +of unconditionally including it). Here is an example from AMD K8. +Note that we can make a variable conditional on the ACPI tables. +\begin{verbatim} +driver-y += northbridge.o +driver-y += misc_control.o +obj-y += get_sblk_pci1234.o +obj-$(CONFIG_HAVE_ACPI_TABLES) += amdk8_acpi.o +\end{verbatim} + +\subsection{southbridge} +\subsubsection{southbridge/Kconfig} +No variables. Source all vendor directory Kconfigs. +\subsubsection{southbridge/Makefile.inc} +No variables. {\em Unconditionally} include all vendor Makefile.inc +\subsubsection{southbridge/$<$vendor$>$/Kconfig} +No variables. Source all chip directory Kconfigs. +\subsubsection{southbridge/$<$vendor$>$/Makefile.inc} +No variables. {\em Conditionally} include all chipset Makefile.inc. The variable +is the name of the part, e.g. +\begin{verbatim} +subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111 +\end{verbatim} +. +\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig} +Typically a small number of variables. One defines the part name. Here is an example +of the variables defined for the K8. +\begin{verbatim} +config SOUTHBRIDGE_AMD_AMD8111 + bool + default n + +\end{verbatim} +\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc} +Typically very small set of rules, and very simple. +Since this file is already conditionally included, +we don't need to test for the chipset CONFIG variable. We +can therefore test other variables (which is part of the reason +we set up conditional inclusion of this file, instead +of unconditionally including it). Here is an example from AMD 8111. +No conditionals in this one yet. +\begin{verbatim} +driver-y += amd8111.o +driver-y += amd8111_usb.o +driver-y += amd8111_lpc.o +driver-y += amd8111_ide.o +driver-y += amd8111_acpi.o +driver-y += amd8111_usb2.o +driver-y += amd8111_ac97.o +driver-y += amd8111_nic.o +driver-y += amd8111_pci.o +driver-y += amd8111_smbus.o +obj-y += amd8111_reset.o +\end{verbatim} + +\subsubsection{vendor and part} +\subsection{southbridge} +\subsubsection{vendor and part} +\subsection{superio} +\subsection{drivers/i2c} +This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed. +To compile in one of these files, name the .o directory. E.g. in serengeti\_cheetah we have: +\begin{verbatim} +\end{verbatim} + +\subsubsection{vendor and part} + +\end{document} diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000000..1e00444bfa --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,71 @@ +# +# Makefile for coreboot paper. +# hacked together by Stefan Reinauer <stepan@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 new file mode 100644 index 0000000000..85ad4d76f9 --- /dev/null +++ b/Documentation/POSTCODES @@ -0,0 +1,26 @@ +------------------------------------------------------------------------------- +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/RFC/chip.tex b/Documentation/RFC/chip.tex new file mode 100644 index 0000000000..5e366b8461 --- /dev/null +++ b/Documentation/RFC/chip.tex @@ -0,0 +1,266 @@ + 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@lanl.gov Fri May 16 10:34:13 2003 +Date: Tue, 13 May 2003 08:11:46 -0600 (MDT) +From: ron minnich <rminnich@lanl.gov> +To: linuxbios@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 new file mode 100644 index 0000000000..6d6c433025 --- /dev/null +++ b/Documentation/RFC/config.tex @@ -0,0 +1,291 @@ + 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 new file mode 100644 index 0000000000..81442e7170 --- /dev/null +++ b/Documentation/abi-data-consumption.txt @@ -0,0 +1,22 @@ +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 new file mode 100644 index 0000000000..453714c574 --- /dev/null +++ b/Documentation/beginverbatim.tex @@ -0,0 +1 @@ +\begin{verbatim} diff --git a/Documentation/cbfs.txt b/Documentation/cbfs.txt new file mode 100644 index 0000000000..7ecc9014a1 --- /dev/null +++ b/Documentation/cbfs.txt @@ -0,0 +1,421 @@ + +Received: from www.crouse-house.com ([199.45.160.146] + for coreboot@coreboot.org; Fri, 19 Dec 2008 23:11:59 +0100 +From: Jordan Crouse <jordan@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@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 new file mode 100644 index 0000000000..bed9599757 --- /dev/null +++ b/Documentation/codeflow.svg @@ -0,0 +1,234 @@ +<?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/coreboot_logo.png b/Documentation/coreboot_logo.png Binary files differnew file mode 100644 index 0000000000..dde1aa68b4 --- /dev/null +++ b/Documentation/coreboot_logo.png diff --git a/Documentation/endverbatim.tex b/Documentation/endverbatim.tex new file mode 100644 index 0000000000..f832f3f23e --- /dev/null +++ b/Documentation/endverbatim.tex @@ -0,0 +1 @@ +\end{verbatim} diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt new file mode 100644 index 0000000000..896ec939d6 --- /dev/null +++ b/Documentation/gcov.txt @@ -0,0 +1,227 @@ +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/hypertransport.svg b/Documentation/hypertransport.svg new file mode 100644 index 0000000000..757e7f4200 --- /dev/null +++ b/Documentation/hypertransport.svg @@ -0,0 +1,59 @@ +<?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/submodules.txt b/Documentation/submodules.txt new file mode 100644 index 0000000000..631e351303 --- /dev/null +++ b/Documentation/submodules.txt @@ -0,0 +1,46 @@ +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. |
