1% 2% This document is released under the GPL 3% Initially written by Stefan Reinauer, <stepan@coresystems.de> 4% 5 6\documentclass[titlepage,12pt]{article} 7\usepackage{a4} 8\usepackage{graphicx} 9\usepackage{url} 10\usepackage[pdftex]{hyperref} 11% \usepackage{makeidx} 12% \makeindex 13 14\hypersetup{ 15 urlbordercolor={1 1 1}, 16 menubordercolor={1 1 1}, 17 linkbordercolor={1 1 1}, 18 colorlinks=false, 19 % pdfpagemode=None, % PDF-Viewer starts without TOC 20 % pdfstartview=FitH, 21 pdftitle={coreboot on AMD64}, 22 pdfauthor={Stefan Reinauer}, 23 pdfsubject={coreboot configuration and build process}, 24 pdfkeywords={coreboot, Opteron, AMD64, configuration, Build} 25} 26 27 28% \newcommand{\sh}[1]{\begin{verbatim}\texttt{#1}\end{verbatim}} 29% \newcommand{\prog}[1]{\textit{#1}} 30 31\setlength{\parindent}{0pt} 32 33\title{coreboot on AMD64} 34\author{Stefan Reinauer $<$stepan@coresystems.de$>$} 35\date{April 19th, 2009} 36 37\begin{document} 38 39\maketitle 40 41\thispagestyle{empty} 42 43\tableofcontents 44 45\newpage 46 47% 48% 1 Abstract 49% 50 51\section{Abstract} 52 53This document targets porting coreboot to new mainboards and creating 54custom firmware images using coreboot. It describes how to build 55coreboot images for the AMD64 platform, including hypertransport 56configuration and pertinent utilities. If you are missing information or 57find errors in the following descriptions, contact 58\href{mailto:stepan@coresystems.de}{\textit{Stefan Reinauer $<$stepan@coresystems.de$>$}} 59 60 61% 62% 2 Changes 63% 64 65\section{Changes} 66 \begin{itemize} 67 \item 2009/04/19 replace LinuxBIOS with coreboot 68 \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ 69 \item 2004/02/10 acpi and option rom updates 70 \item 2003/11/18 initial release 71 \end{itemize} 72 73 74 75% 76% 3 What is coreboot 77% 78 79\section{What is coreboot?} 80 81coreboot aims to replace the normal BIOS found on x86, AMD64, PPC, 82Alpha, and other machines with a Linux kernel that can boot Linux from a cold 83start. The startup code of an average coreboot port is about 500 lines of 84assembly and 5000 lines of C. It executes 16 instructions to get into 32bit 85protected mode and then performs DRAM and other hardware initializations 86required before Linux can take over. 87 88The projects primary motivation initially was maintenance of large 89clusters. Not surprisingly interest and contributions have come from 90people with varying backgrounds. Nowadays a large and growing number of 91Systems can be booted with coreboot, including embedded systems, 92Desktop PCs and Servers. 93 94% 95% 4 Build Requirements 96% 97 98\section{Build Requirements} 99To build coreboot for AMD64 from the sources you need a recent Linux 100system for x86 or AMD64. SUSE Linux 8.2 or 9.0 are known to work fine. 101The following toolchain is recommended: 102 103 \begin{itemize} 104 \item GCC 3.3.1 105 \item binutils 2.14.90.0.5 106 \item Python 2.3 107 \item CVS 1.11.6 108 \end{itemize} 109 110\textbf{NOTE:} Later versions should also work. Prior versions might lead to problems. 111 112\newpage 113 114% 115% 5 Getting the Sources 116% 117 118\section{Getting the Sources} 119 120The latest coreboot sources are available via subversion. The subversion 121repository is maintained at SourceForge.net (the project name is 122\emph{FreeBIOS}). First you should create a directory for your 123coreboot trees: 124 125{ \small 126\begin{verbatim} 127$ mkdir coreboot 128$ cd coreboot 129\end{verbatim} 130} 131 132You can get the entire source tree via SVN: 133 134{ \small 135\begin{verbatim} 136$ svn co svn://coreboot.org/repos/trunk/coreboot-v2 137\end{verbatim} 138} 139 140Once the source tree is checked out, it can be updated with: 141 142{ \small 143\begin{verbatim} 144% svn update 145\end{verbatim} 146} 147 148For the case your corporate firewall blocks port 3690 (subversion) we set up a 149snapshot site that keeps the last few hundred source code revisions. It 150is available at \url{http://qa.coreboot.org/}. 151Due to major structural enhancements to \hbox{coreboot}, AMD64 support 152is only available in the \texttt{coreboot-v2} tree. This tree reflects (as 153of November 2003) coreboot version 1.1.5 and will lead to coreboot 2.0 154when finished. Most x86 hardware is currently only supported by the 155coreboot 1.0 tree. 156 157% 158% 6 coreboot configuration overview 159% 160 161\section{coreboot configuration overview} 162To support a large variety of existing hardware coreboot allows for a 163lot of configuration options that can be tweaked in several ways: 164 165\begin{itemize} 166\item 167Firmware image specific configuration options can be set in the image 168configuration file which is usually found in 169\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/}. Such 170options are the default amount of output verbosity during bootup, image 171size, use of fallback mechanisms, firmware image size and payloads 172(Linux Kernel, Bootloader...) The default configuration file name is 173\texttt{Config.lb}, but coreboot allows multiple configurations to 174reside in that directory. 175 176\item Mainboard specific configuration options can be set in the 177mainboard configuration file placed in 178\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$}. The 179mainboard configuration file is always called \texttt{Config.lb}. It 180contains information on the onboard components of the mainboard like 181CPU type, northbridge, southbridge, hypertransport configuration and 182SuperIO configuration. This configuration file also allows to include 183addon code to hook into the coreboot initialization mechanism at 184basically any point. 185 186\end{itemize} 187 188This document describes different approaches of changing and configuring the 189coreboot source tree when building for AMD64. 190 191% 192% 7 Building coreboot 193% 194 195\section{Building coreboot} 196One of the design goals for building coreboot was to keep object files 197out of the source tree in a separate place. This is mandatory for 198building parallel coreboot images for several distinct mainboards 199and/or platforms. Therefore building coreboot consists of two steps: 200\begin{itemize} 201\item 202creating a build tree which holds all files automatically created by the 203configuration utility and the object files 204\item 205compiling the coreboot code and creating a flashable firmware image. 206\end{itemize} 207 208The first of these two steps is accomplished by the \texttt{buildtarget} 209script found in \texttt{coreboot-v2/targets/}. To build coreboot for 210instance for the AMD Solo Athlon64 mainboard enter: 211 212\begin{verbatim} 213% cd coreboot-v2/targets 214% ./buildtarget amd/solo 215\end{verbatim} 216 217This will create a directory containing a Makefile and other software 218components needed for this build. The directory name is defined in the 219firmware image specific configuration file. In the case of AMD's Solo 220mainboard the default directory resides in 221\texttt{coreboot-v2/targets/amd/solo/solo}. To build the coreboot image, do 222 223\begin{verbatim} 224% cd amd/solo/solo 225% make 226\end{verbatim} 227 228The coreboot image filename is specified in the firmware image specific 229configuration file. The default filename for AMD's Solo mainboard is 230\texttt{solo.rom}. 231 232% 233% 8 Programming coreboot to flash memory 234% 235 236\section{Programming coreboot to flash memory} 237The image resulting from a coreboot build can be directly programmed to 238a flash device, either using a hardware flash programmer or by using the 239Linux flash driver devbios or mtd. This document assumes that you use a 240hardware flash programmer. If you are interested in doing in-system 241software flash programming, find detailed information: 242 243\begin{itemize} 244\item \url{http://www.openbios.org/development/devbios.html} (/dev/bios) 245\item \url{http://www.linux-mtd.infradead.org/} (Memory Technology Device Subsystem MTD) 246\end{itemize} 247 248\newpage 249 250% 251% 9 coreboot configuration 252% 253 254\section{coreboot configuration} 255The following chapters will cope with configuring coreboot. All 256configuration files share some basic rules 257\begin{itemize} 258\item 259The default configuration file name in coreboot is \texttt{Config.lb}. 260\item 261All variables used in a configuration file have to be declared in this 262file with \texttt{uses VARNAME} before usage. 263\item 264Comments can be added on a new line by using the comment identifier 265\texttt{\#} at the beginning of the line. 266\item 267coreboot distinguishes between statements and options. Statements cause 268the coreboot configuration mechanism to act, whereas options set 269variables that are used by the build scripts or source code. 270\item 271Default configuration values can be set in the mainboard configuration 272files (keyword default) 273\item 274Option overrides to the default configuration can only be specified in 275the build target configuration file 276\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb} 277(keyword option) 278\end{itemize} 279 280\subsection{Common Configuration Statements} 281 282\begin{itemize} 283 284\item \begin{verbatim}uses\end{verbatim} 285 286All local configuration variables have to be declared before they can be 287used. Example: 288\begin{verbatim} 289 uses CONFIG_ROM_IMAGE_SIZE 290\end{verbatim} 291 292\textbf{NOTE:} Only configuration variables known to the configuration 293system can be used in configuration files. coreboot checks 294\texttt{coreboot-v2/src/config/Options.lb} to see whether a configuration 295variable is known. 296 297\item \begin{verbatim}default\end{verbatim} 298 299The \texttt{default} statement is used to set a configuration variable 300with an overridable default value. It is commonly used in mainboard 301configuration files. 302 303Example: 304 305\begin{verbatim} 306 default CONFIG_ROM_IMAGE_SIZE=0x10000 307\end{verbatim} 308 309It is also possible to assign the value of one configuration variable to 310another one, i.e.: 311 312\begin{verbatim} 313 default CONFIG_FALLBACK_SIZE=CONFIG_ROM_SIZE 314\end{verbatim} 315 316Also, simple expressions are allowed: 317 318\begin{verbatim} 319 default CONFIG_FALLBACK_SIZE=(CONFIG_ROM_SIZE - NORMAL_SIZE) 320\end{verbatim} 321 322If an option contains a string, this string has to be protected with 323quotation marks: 324 325\begin{verbatim} 326 default CC="gcc -m32" 327\end{verbatim} 328 329\item \begin{verbatim}option\end{verbatim} 330 331The \texttt{option} statement basically behaves identically to the 332\texttt{default} statement. But unlike default it can only be used in 333build target configuration files 334(\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$}). The option 335statement allows either to set new options or to override default values 336set with the default statement in a mainboard configuration file. 337Syntax and application are the same as with default. 338 339\end{itemize} 340 341\subsection{Firmware image specific configuration} 342coreboot allows to create different firmware images for the same 343hardware. Such images can differ in the amount of output they produce, 344the payload, the number of subimages they consist of etc. 345 346The firmware image specific configuration file can be found in \\ 347\texttt{coreboot-v2/targets/$<$vendor$>$/<mainboard$>$}. 348 349\subsubsection{Firmware image specific keywords} 350In addition to the above described keywords the following statements are 351available in firmware image specific configuration files: 352 353\begin{itemize} 354\item \begin{verbatim}romimage\end{verbatim} 355 356The \texttt{romimage} definition describes a single rom build within the 357final coreboot image. Normally there are two romimage definitions per 358coreboot build: \texttt{normal} and \texttt{fallback}. 359 360Each \texttt{romimage} section needs to specify a mainboard directory and a 361payload. The mainboard directory contains the mainboard specific 362configuration file and source code. It is specified relatively to 363\texttt{coreboot-v2/src/mainboard}. The payload definition is an absolute 364path to a static elf binary (i.e Linux kernel or etherboot) 365 366\begin{verbatim} 367romimage "normal" 368 option CONFIG_USE_FALLBACK_IMAGE=0 369 option CONFIG_ROM_IMAGE_SIZE=0x10000 370 option COREBOOT_EXTRA_VERSION=".0Normal" 371 mainboard amd/solo 372 payload /suse/stepan/tg3ide_ 373 disk.zelf 374end 375\end{verbatim} 376 377\item \begin{verbatim}buildrom\end{verbatim} 378 379The \texttt{buildrom} statement is used to determine which of the 380coreboot image builds (created using \texttt{romimage}) are packed 381together to the final coreboot image. It also specifies the order of 382the images and the final image size: 383 384\begin{verbatim} 385 buildrom ./solo.rom CONFIG_ROM_SIZE "normal" "fallback" 386\end{verbatim} 387 388\end{itemize} 389 390 391\subsubsection{Firmware image configuration options} 392In addition to the definitions described above there are a number of 393commonly used options. Configuration options set in the firmware image 394specific configuration file can override default selections from the 395Mainboard specific configuration. See above examples about 396option on how to set them. 397 398\begin{itemize} 399 400\item \begin{verbatim}CC\end{verbatim} 401 402Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to 403\texttt{gcc -m32} for compiling AMD64 coreboot images on an AMD64 404machine. 405 406\item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim} 407 408Use new \textit{chip\_configure} method for configuring (nonpci) 409devices. Set to \texttt{1} for all AMD64 mainboards. 410 411\item \begin{verbatim}CONFIG_MAXIMUM_CONSOLE_LOGLEVEL\end{verbatim} 412 413Errors or log messages up to this level can be printed. Default is 414\texttt{8}, minimum is \texttt{0}, maximum is \texttt{10}. 415 416\item \begin{verbatim}CONFIG_DEFAULT_CONSOLE_LOGLEVEL\end{verbatim} 417 418Console will log at this level unless changed. Default is \texttt{7}, 419minimum is \texttt{0}, maximum is \texttt{10}. 420 421\item \begin{verbatim}CONFIG_CONSOLE_SERIAL8250\end{verbatim} 422 423Log messages to 8250 uart based serial console. Default is \texttt{0} 424(don't log to serial console). This value should be set to \texttt{1} 425for all AMD64 builds. 426 427\item \begin{verbatim}CONFIG_ROM_SIZE\end{verbatim} 428 429Size of final ROM image. This option has no default value. 430 431\item \begin{verbatim}CONFIG_FALLBACK_SIZE\end{verbatim} 432 433Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:} 434This does not include the fallback payload. 435 436\item \begin{verbatim}CONFIG_HAVE_OPTION_TABLE\end{verbatim} 437 438Export CMOS option table. Default is \texttt{0}. Set to \texttt{1} if 439your mainboard has CMOS memory and you want to use it to store 440coreboot parameters (Loglevel, serial line speed, ...) 441 442\item \begin{verbatim}CONFIG_ROM_PAYLOAD\end{verbatim} 443 444Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_PAYLOAD}, which 445will boot from an IDE disk) 446 447\item \begin{verbatim}CONFIG_HAVE_FALLBACK_BOOT\end{verbatim} 448 449Set to \texttt{1} if fallback booting is required. Defaults to 450\texttt{0}. 451 452\end{itemize} 453 454 455The following options should be used within a romimage section: 456 457\begin{itemize} 458 459\item \begin{verbatim}CONFIG_USE_FALLBACK_IMAGE\end{verbatim} 460 461Set to \texttt{1} to build a fallback image. Defaults to \texttt{0} 462 463\item \begin{verbatim}CONFIG_ROM_IMAGE_SIZE\end{verbatim} 464 465Default image size. Defaults to \texttt{65535} bytes. 466 467\item \begin{verbatim}COREBOOT_EXTRA_VERSION\end{verbatim} 468 469coreboot extra version. This option has an empty string as default. Set 470to any string to add an extra version string to your coreboot build. 471 472\end{itemize} 473 474\newpage 475 476\subsection{Mainboard specific configuration} 477 478Mainboard specific configuration files describe the onboard 479mainboard components, i.e. bridges, number and type of CPUs. They also 480contain rules for building the low level start code which is translated 481using romcc and/or the GNU assembler. This code enables caches and 482registers, early mtrr settings, fallback mechanisms, dram init and 483possibly more. 484 485\textbf{NOTE:} The \texttt{option} keyword can not be used in mainboard 486specific configuration files. Options shall instead be set using the 487\texttt{default} keyword so that they can be overridden by the image 488specific configuration files if needed. 489 490\subsubsection{Mainboard specific keywords} 491 492The following statements are used in mainboard specific configuration 493files: 494 495\begin{itemize} 496\item \begin{verbatim}arch\end{verbatim} 497 498Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.\\ 499Example: 500 501\begin{verbatim} 502 arch i386 end 503\end{verbatim} 504 505\item \begin{verbatim}cpu\end{verbatim} 506 507The cpu statement is needed once per possibly available CPU. In a 508one-node system, write: 509 510\begin{verbatim} 511 cpu k8 "cpu0" end 512\end{verbatim} 513 514\item \begin{verbatim}driver\end{verbatim} 515 516The \texttt{driver} keyword adds an object file to the driver section of a 517coreboot image. This means it can be used by the PCI device 518initialization code. Example: 519 520\begin{verbatim} 521 driver mainboard.o 522\end{verbatim} 523 524\item \begin{verbatim}object\end{verbatim} 525 526The \texttt{object} keyword adds an object file to the coreboot image. 527Per default the object file will be compiled from a \texttt{.c} file 528with the same name. Symbols defined in such an object file can be used 529in other object files and drivers. Example: 530 531\begin{verbatim} 532 object reset.o 533\end{verbatim} 534 535\item \begin{verbatim}makerule\end{verbatim} 536 537This keyword can be used to extend the existing file creation rules 538during the build process. This is useful if external utilities have to 539be used for the build. coreboot on AMD64 uses romcc for it's early 540startup code placed in auto.c. 541 542To tell the configuration mechanism how to build \texttt{romcc} files, 543do: 544 545\begin{verbatim} 546makerule ./auto.E 547 depends "$(CONFIG_MAINBOARD)/auto.c option_table.h ./romcc" 548 action "./romcc -E -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ 549 $(CONFIG_MAINBOARD)/auto.c -o $@" 550end 551makerule ./auto.inc 552 depends "$(CONFIG_MAINBOARD)/auto.c option_table.h ./romcc" 553 action "./romcc -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ 554 $(CONFIG_MAINBOARD)/auto.c -o $@" 555end 556\end{verbatim} 557 558Each \texttt{makerule} section contains file dependencies (using the 559texttt{depends} keyword) and an action that is taken when the dependencies 560are satisfied (using the \texttt{action} keyword). 561 562\item \begin{verbatim}mainboardinit\end{verbatim} 563 564With the mainboardinit keyword it's possible to include assembler code 565directly into the coreboot image. This is used for early infrastructure 566initialization, i.e. to switch to protected mode. Example: 567 568\begin{verbatim} 569 mainboardinit cpu/i386/entry16.inc 570\end{verbatim} 571 572\item \begin{verbatim}ldscript\end{verbatim} 573 574The GNU linker ld is used to link object files together to a coreboot 575ROM image. 576 577Since it is a lot more comfortable and flexible to use the GNU linker 578with linker scripts (ldscripts) than to create complex command line 579calls, coreboot features including linker scripts to control image 580creation. Example: 581 582\begin{verbatim} 583 ldscript /cpu/i386/entry16.lds 584\end{verbatim} 585 586 587\item \begin{verbatim}dir\end{verbatim} 588 589coreboot reuses as much code between the different ports as possible. 590To achieve this, commonly used code can be stored in a separate 591directory. For a new mainboard, it is enough to know that the code in 592that directory can be used as is. 593 594coreboot will also read a \texttt{Config.lb} file stored in that 595directory. This happens with: 596 597\begin{verbatim} 598 dir /pc80 599\end{verbatim} 600 601 602\item \begin{verbatim}config\end{verbatim} 603 604This keyword is needed by the new chip configuration scheme. Should be 605used as: 606 607\begin{verbatim} 608 config chip.h 609\end{verbatim} 610 611\item \begin{verbatim}register\end{verbatim} 612The \texttt{register} keyword can occur in any section, passing 613additional \\ 614parameters to the code handling the associated device. 615Example: 616 617\begin{verbatim} 618 register "com1" = "{1, 0, 0x3f8, 4}" 619\end{verbatim} 620 621\item \begin{verbatim}northbridge\end{verbatim} 622 623The \texttt{northbridge} keyword describes a system northbridge. Some 624systems, like AMD64, can have more than one northbridge, i.e. one per 625CPU node. Each northbridge is described by the path to the northbridge 626code in coreboot (relative to \texttt{coreboot-v2/src/northbridge}), i.e. 627\texttt{amd/amdk8} and a unique name (i.e \texttt{mc0}) \\ 628Example: 629 630\begin{verbatim} 631 northbridge amd/amdk8 "mc0" 632 [..] 633 end 634\end{verbatim} 635 636\item \begin{verbatim}southbridge\end{verbatim} 637 638To simplify the handling of bus bridges in a coreboot system, all 639bridges available in a system that are not northbridges (i.e AGP, IO, 640PCIX) are seen as southbridges. 641 642Since from the CPUs point of view any southbridge is connected via the 643northbridge, a southbridge section is declared within the northbridge 644section of the north bridge it is attached to. 645 646Like the northbridge, any other bridge is described by the path to it's 647driver code, and a unique name. If the described bridge is a 648hypertransport device, the northbridge's hypertransport link it connects 649to can be specified using the \texttt{link} keyword. Example: 650 651\begin{verbatim} 652northbridge amd/amdk8 "mc0" 653 [..] 654 southbridge amd/amd8111 "amd8111" link 0 655 [..] 656 end 657 [..] 658end 659\end{verbatim} 660 661\item \begin{verbatim}pci\end{verbatim} 662 663The \texttt{pci} keyword can only occur within a \texttt{northbridge} or 664\texttt{southbridge} section. It is used to describe the PCI devices 665that are provided by the bridge. Generally all bridge sections have a 666couple of \texttt{pci} keywords. 667 668The first occurrence of the \texttt{pci} keyword tells coreboot where 669the bridge devices start, relative to the PCI configuration space used 670by the bridge. The following occurences of the \texttt{pci} keyword 671describe the provided devices. 672 673Adding the option \texttt{on} or \texttt{off} to a PCI device will 674enable or disable this device. This feature can be used if some bridge 675devices are not wired to hardware outputs and thus are not used. 676 677Example: 678 679\begin{verbatim} 680northbridge amd/amdk8 "mc1" 681 pci 0:19.0 682 pci 0:19.0 683 pci 0:19.0 684 pci 0:19.1 685 pci 0:19.2 686 pci 0:19.3 687end 688\end{verbatim} 689 690or 691 692\begin{verbatim} 693southbridge amd/amd8111 "amd8111" link 0 694 pci 0:0.0 695 pci 0:1.0 on 696 pci 0:1.1 on 697 pci 0:1.2 on 698 pci 0:1.3 on 699 pci 0:1.5 off 700 pci 0:1.6 off 701 pci 1:0.0 on 702 pci 1:0.1 on 703 pci 1:0.2 on 704 pci 1:1.0 off 705 [..] 706end 707\end{verbatim} 708 709\item \begin{verbatim}superio\end{verbatim} 710 711SuperIO devices are basically handled like brigdes. They are taking 712their driver code from \texttt{coreboot-v2/src/superio/}. They don't 713provide a PCI compatible configuration interface, but instead are ISA 714PnP devices. Normally they are connected to a southbridge. If this is 715the case, the \texttt{superio} section will be a subsection of the 716\texttt{southbridge} section of the southbridge it is connected to. 717Example: 718 719\begin{verbatim} 720superio nsc/pc87360 link 1 721 pnp 2e.0 722 pnp 2e.1 723 pnp 2e.2 724 pnp 2e.3 725 pnp 2e.4 726 pnp 2e.5 727 pnp 2e.6 728 pnp 2e.7 729 pnp 2e.8 730 pnp 2e.9 731 pnp 2e.a 732 register "com1" = "{1, 0, 0x3f8, 4}" 733 register "lpt" = "{1}" 734end 735\end{verbatim} 736 737\end{itemize} 738 739\newpage 740 741\subsubsection{Mainboard specific configuration options} 742 743The following options are commonly used in mainboard specific 744configuration files. 745 746They should be set using the \texttt{default} keyword: 747 748\begin{itemize} 749 750\item \begin{verbatim}CONFIG_HAVE_HARD_RESET\end{verbatim} 751 752If set to \texttt{1}, this option defines that there is a hard reset 753function for this mainboard. This option is not defined per default. 754 755\item \begin{verbatim}CONFIG_HAVE_PIRQ_TABLE\end{verbatim} 756 757If set to \texttt{1}, this option defines that there is an IRQ Table for 758this mainboard. This option is not defined per default. 759 760\item \begin{verbatim}CONFIG_IRQ_SLOT_COUNT\end{verbatim} 761 762Number of IRQ slots. This option is not defined per default. 763 764\item \begin{verbatim}CONFIG_HAVE_MP_TABLE\end{verbatim} 765 766Define this option to build an MP table (v1.4). The default is not to 767build an MP table. 768 769\item \begin{verbatim}CONFIG_HAVE_OPTION_TABLE\end{verbatim} 770 771Define this option to export a CMOS option table. The default is not to 772export a CMOS option table. 773 774\item \begin{verbatim}CONFIG_SMP\end{verbatim} 775 776Set this option to \texttt{1} if the mainboard supports symmetric 777multiprocessing (SMP). This option defaults to \texttt{0} (no SMP). 778 779\item \begin{verbatim}CONFIG_MAX_CPUS\end{verbatim} 780 781If \begin{verbatim}CONFIG_SMP\end{verbatim} is set, this option defines 782the maximum number of CPUs (i.e. the number of CPU sockets) in the 783system. Defaults to \texttt{1}. 784 785\item \begin{verbatim}CONFIG_IOAPIC\end{verbatim} 786 787Set this option to \texttt{1} to enable IOAPIC support. This is 788mandatory if you want to boot a 64bit Linux kernel on an AMD64 system. 789 790\item \begin{verbatim}CONFIG_STACK_SIZE\end{verbatim} 791 792coreboot stack size. The size of the function call stack defaults to 793\texttt{0x2000} (8k). 794 795\item \begin{verbatim}CONFIG_HEAP_SIZE\end{verbatim} 796 797coreboot heap size. The heap is used when coreboot allocates memory 798with malloc(). The default heap size is \texttt{0x2000}, but AMD64 boards 799generally set it to \texttt{0x4000} (16k) 800 801\item \begin{verbatim}CONFIG_XIP_ROM_BASE\end{verbatim} 802 803Start address of area to cache during coreboot execution directly from 804ROM. 805 806\item \begin{verbatim}CONFIG_XIP_ROM_SIZE\end{verbatim} 807 808Size of area to cache during coreboot execution directly from ROM 809 810\item \begin{verbatim}CONFIG_COMPRESS\end{verbatim} 811 812Set this option to \texttt{1} for a compressed image. If set to 813\texttt{0}, the image is bigger but will start slightly faster (since no 814decompression is needed). 815 816\end{itemize} 817 818 819\newpage 820 821% 822% 10. Tweaking the source code 823% 824 825\section{Tweaking the source code} 826Besides configuring the existing code it is sometimes necessary or 827desirable to tweak certain parts of coreboot by direct changes to the 828code. This chapter covers some possible enhancements and changes that 829are needed when porting coreboot to a new mainboard or just come 830handy now and then. 831 832\subsection{Hypertransport configuration} 833Before coreboot is able to activate all CPUs and detect bridges 834attached to these CPUs (and thus, see all devices attached to the 835system) it has to initialize the coherent hypertransport devices. 836 837The current algorithms to do coherent hypertransport initialization are 838not fully, automatically evaluating the hypertransport chain graph. 839Therefore the code needs to be adapted when porting coreboot to a new 840AMD64 mainboard. An example arrangement of hypertransport devices 841looks like this: 842 843\begin{figure}[htb] 844\centering 845\includegraphics[scale=1.0]{hypertransport.pdf} 846\caption{Example: Hypertransport Link Connections} 847\label{fix:hypertransport} 848\end{figure} 849 850Each hypertransport device has one to three hypertransport links that 851are used for device interconnection. These links are called LDT$[$012$]$, or 852accordingly UP, ACROSS, DOWN. Communication between the hypertransport 853devices can be freely routed, honoring the physical wiring. Teaching the 854coherent hypertransport initialization algorithm this wiring happens in 855two steps. 856 857\newpage 858 859\begin{enumerate} 860\item Setting outgoing connections 861The algorithm needs to know which outgoing port of a CPU node is 862connected to the directly succeeding node. This is done in 863\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/auto.c} 864with a number of preprocessor defines (one define for two-node systems, 865three defines for four-node systems). 866 867The ports in question are flagged with a circle in the graph for 868illustration. For the example graph above (all outgoing connections are 869realized using LDT1/ACROSS) the defines are: 870 871\begin{verbatim} 872#define CONNECTION_0_1 ACROSS 873#define CONNECTION_0_2 ACROSS 874#define CONNECTION_1_3 ACROSS 875\end{verbatim} 876 877\item Describing routing information between CPUs. 878 879There are basically three different message types for hypertransport 880communication: 881\begin{enumerate} 882\item request packages 883\item response packages 884\item broadcast packages 885\end{enumerate} 886 887These three message types are routed using different hypertransport 888ports. The routing information is written to the AMD K8 routing table. 889In an Nnode system this routing table consists of 3*N*N entries , one 890for each message type and for each possible CPU --> CPU communication. For 891simplicity coreboot keeps the 3 routing entries for each CPU --> CPU 892communication in one machine word. The routing table of each node looks 893like this: 894 895\begin{verbatim} 896/* Routing Table for Node i 897 * 898 * F0: 0x40, 0x44, 0x48, 0x4c, 0x50, 0x54, 0x58, 0x5c 899 * i: 0, 1, 2, 3, 4, 5, 6, 7 900 * 901 * [ 0: 3] Request Route 902 * [0] Route to this node 903 * [1] Route to Link 0 904 * [2] Route to Link 1 905 * [3] Route to Link 2 906 * [11: 8] Response Route 907 * [0] Route to this node 908 * [1] Route to Link 0 909 * [2] Route to Link 1 910 * [3] Route to Link 2 911 * [19:16] Broadcast route 912 * [0] Route to this node 913 * [1] Route to Link 0 914 * [2] Route to Link 1 915 * [3] Route to Link 2 916 */ 917\end{verbatim} 918 919The routing table is passed to the coherent hypertransport 920initialization algorithm by defining a function called 921\texttt{generate\_row()} in \texttt{auto.c}: 922 923\begin{verbatim} 924static unsigned int generate_row 925 (uint8_t node, uint8_t row, uint8_t maxnodes) 926\end{verbatim} 927 928This function is trivial if there is only one CPU in the system, since 929no routing has to be done: 930 931\begin{verbatim} 932static unsigned int generate_row 933 (uint8_t node, uint8_t row, uint8_t maxnodes) 934{ 935 return 0x00010101; /* default row entry */ 936} 937\end{verbatim} 938 939On a two-node system things look slightly more complicated. Since the 940coherent hypertransport initialization algorithm works by consecutively 941enabling CPUs, it contains routing information for driving the system 942with one node and two nodes: 943 944\begin{verbatim} 945static unsigned int generate_row 946 (uint8_t node, uint8_t row, uint8_t maxnodes) 947{ 948 uint32_t ret=0x00010101; /* default row entry */ 949 static const unsigned int rows_2p[2][2] = { 950 { 0x00050101, 0x00010404 }, 951 { 0x00010404, 0x00050101 } 952 }; 953 if(maxnodes>2) maxnodes=2; 954 if (!(node>=maxnodes || row>=maxnodes)) { 955 ret=rows_2p[node][row]; 956 } 957 return ret; 958} 959\end{verbatim} 960 961Systems with four nodes have to contain routing information for one, two 962and four-node setups: 963 964\begin{verbatim} 965static unsigned int generate_row 966 (uint8_t node, uint8_t row, uint8_t maxnodes) 967{ 968 uint32_t ret=0x00010101; /* default row entry */ 969 static const unsigned int rows_2p[2][2] = { 970 { 0x00030101, 0x00010202 }, 971 { 0x00010202, 0x00030101 } 972 }; 973 static const unsigned int rows_4p[4][4] = { 974 { 0x00070101, 0x00010202, 0x00030404, 0x00010204 }, 975 { 0x00010202, 0x000b0101, 0x00010208, 0x00030808 }, 976 { 0x00030808, 0x00010208, 0x000b0101, 0x00010202 }, 977 { 0x00010204, 0x00030404, 0x00010202, 0x00070101 } 978 }; 979 if (!(node>=maxnodes || row>=maxnodes)) { 980 if (maxnodes==2) 981 ret=rows_2p[node][row]; 982 if (maxnodes==4) 983 ret=rows_4p[node][row]; 984 } 985 return ret; 986} 987\end{verbatim} 988\end{enumerate} 989 990\subsection{DRAM configuration} 991Setting up the RAM controller(s) is probably the most complex part of 992coreboot. Basically coreboot serially initializes all RAM controllers 993in the system, using SPDROM (serial presence detect) data to set 994timings, size and other properties. The SPD data is usually read 995utilizing the I2C SMBUS interface of the southbridge. 996 997There is one central data structure that describes the RAM controllers 998available on an AMD64 system and the associated devices: 999 1000\begin{verbatim}
1001struct mem_controller { 1002 unsigned node_id; 1003 device_t f0, f1, f2, f3; 1004 uint8_t channel0[4]; 1005 uint8_t channel1[4]; 1006}; 1007\end{verbatim} 1008 1009Available mainboard implementations and CPUs create the need to add 1010special setup code to RAM initialization in a number of places. 1011coreboot provides hooks to easily add code in these places without 1012having to change the generic code. Whether these hooks have to be used 1013depends on the mainboard design. In many cases the functions executed 1014by the hooks just carry out trivial default settings or they are even 1015empty. 1016 1017Some mainboard/CPU combinations need to trigger an additional memory 1018controller reset before the memory can be initialized properly. This is, 1019for example, used to get memory working on preC stepping AMD64 1020processors. coreboot provides two hooks for triggering onboard memory 1021reset logic: 1022 1023\begin{itemize} 1024\item \begin{verbatim}static void memreset_setup(void)\end{verbatim} 1025\item \begin{verbatim}static void memreset(int controllers, const struct 1026 mem_controller *ctrl)\end{verbatim} 1027\end{itemize} 1028 1029Some mainboards utilize an SMBUS hub or possibly other mechanisms to 1030allow using a large number of SPDROMs and thus ram sockets. The result 1031is that only the SPDROM information of one cpu node is visible at a 1032time. The following function, defined in \texttt{auto.c}, is called every time 1033before a memory controller is initialized and gets the memory controller 1034information of the next controller as a parameter: 1035 1036\begin{verbatim} 1037static inline void activate_spd_rom (const struct mem_controller *ctrl) 1038\end{verbatim} 1039 1040The way SMBUS hub information is coded into the \texttt{mem\_controller} 1041structure is mainboard implementation specific and not 1042described here. See \texttt{coreboot-v2/src/mainboard/amd/quartet/auto.c} 1043for an example. 1044 1045coreboot folks have agreed on SPD data being the central information 1046source for RAM specific information. But not all mainboards/RAM 1047modules feature a physical SPD ROM. To still allow an easy to use SPD 1048driven setup, there is a hook that abstracts reading the SPD ROM 1049ingredients that are used by the memory initialization mechanism: 1050 1051\begin{verbatim} 1052static inline int spd_read_byte(unsigned device, unsigned address) 1053\end{verbatim} 1054 1055This function, defined in \texttt{auto.c}, directly maps it's calls to 1056\texttt{smbus\_read\_byte()} calls if SPD ROM information is read via 1057the I2C SMBUS: 1058 1059\begin{verbatim} 1060static inline int spd_read_byte(unsigned device, unsigned address) 1061{ 1062 return smbus_read_byte(device & 0xff, address); 1063} 1064\end{verbatim} 1065 1066If there is no SPD ROM available in the system design, this function 1067keeps an array of SPD ROM information hard coded per logical RAM module. 1068It returns the faked' SPD ROM information using device and address 1069as indices to this array. 1070 1071 1072\subsection {IRQ Tables} 1073 1074Mainboards that provide an IRQ table should have the following two 1075variables set in their \texttt{Config.lb} file: 1076 1077\begin{verbatim} 1078default CONFIG_HAVE_PIRQ_TABLE=1 1079default CONFIG_IRQ_SLOT_COUNT=7 1080\end{verbatim} 1081 1082This will make coreboot look for the file \\ 1083\texttt{coreboot-v2/src/mainboard/<vendor>/<mainboard>/irq\_tables.c} which 1084contains the source code definition of the IRQ table. coreboot corrects 1085small inconsistencies in the IRQ table during startup (checksum and 1086number of entries), but it is not yet writing IRQ tables in a completely 1087dynamic way. 1088 1089\textbf{NOTE:} To get Linux to understand and actually use the IRQ 1090table, it is not always a good idea to specify the vendor and device id 1091of the actually present interrupt router device. Linux 2.4 for example 1092does not know about the interrupt router of the AMD8111 southbridge. In 1093such cases it is advised to choose the vendor/device id of a compatible 1094device that is supported by the Linux kernel. In case of the AMD8111 1095interrupt router it is advised to specify the AMD768/Opus interrupt 1096controller instead (vendor id=\texttt{0x1022}, device id=\texttt{0x7443}) 1097 1098\subsection {MP Tables} 1099 1100coreboot contains code to create MP tables conforming the 1101Multiprocessor Specification V1.4. To include an MP Table in a coreboot 1102image, the following configuration variables have to be set (in the 1103mainboard specific configuration file 1104\texttt{coreboot-v2/src/mainboard/<vendor><mainboard>/Config.lb}): 1105 1106\begin{verbatim} 1107default CONFIG_SMP=1 1108default CONFIG_MAX_CPUS=1 # 2,4,.. 1109default CONFIG_HAVE_MP_TABLE=1 1110\end{verbatim} 1111 1112coreboot will then look for a function for setting up the MP table in 1113the file \texttt{coreboot-v2/src/mainboard<vendor>/<mainboard>/mptable.c}: 1114 1115\begin{verbatim} 1116void *smp_write_config_table(void *v, unsigned long * processor_map) 1117\end{verbatim} 1118 1119MP Table generation is still somewhat static, i.e. changing the bus 1120numbering will force 1121you to adopt the code in mptable.c. This is subject to change in future 1122revisions. 1123 1124\subsection {ACPI Tables} 1125 1126There is initial ACPI support in coreboot now. Currently the only gain with 1127this is the ability to use HPET timers in Linux. To achieve this, there is a 1128framework that can generate the following tables: 1129\begin{itemize} 1130\item RSDP 1131\item RSDT 1132\item MADT 1133\item HPET 1134\end{itemize} 1135 1136To enable ACPI in your coreboot build, add the following lines to your 1137configuration files: 1138\begin{verbatim} 1139uses CONFIG_HAVE_ACPI_TABLES 1140[..] 1141option CONFIG_HAVE_ACPI_TABLES=1 1142\end{verbatim} 1143 1144To keep Linux doing it's pci ressource allocation based on IRQ tables and MP 1145tables, you have to specify the kernel parameter \texttt{pci=noacpi} otherwise 1146your PCI devices won't get interrupts. 1147It's likely that more ACPI support will follow, when there is need for certain 1148features. 1149 1150\subsection{POST} 1151coreboot has three different methods of handling POST codes. They can 1152be triggered using configuration file options. 1153\begin{itemize} 1154\item 1155\emph{Ignore POST completely}. No early code debugging is possible with 1156this setting. Set the configuration variable \texttt{NO\_POST} to 1157\texttt{1} to switch off all POST handling in coreboot. 1158\item 1159\emph{Normal IO port 80 POST}. This is the default behavior of 1160coreboot. No configuration variables have to be set. To be able to see 1161port 80 POST output, you need a POST expansion card for ISA or PCI. Port 116280 POST allows simple debugging without any other output method 1163available (serial interface or VGA display) 1164\item 1165\emph{Serial POST}. 1166This option allows to push POST messages to the serial interface instead 1167of using IO ports. \textbf{NOTE:} The serial interface has to be 1168initialized before serial POST can work. To use serial POST, set the 1169configuration variable \texttt{CONFIG\_SERIAL\_POST} to the value 1. 1170\end{itemize} 1171 1172 1173\subsection{HDT Debugging} 1174If you are debugging your coreboot code with a Hardware Debug Tool 1175(HDT), you can find the source code line for a given physical EIP 1176address as follows: Look the address up in the file linuxbios.map. Then 1177search the label Lxx in the file auto.inc created by romcc. The original 1178source code file and line number is mentioned in auto.inc. 1179 1180 1181\subsection{Device Drivers} 1182With only a few data structures coreboot features a simple but flexible 1183device driver interface. This interface is not intended for autonomously 1184driving the devices but to initialize all system components so that they 1185can be used by the booted operating system. 1186 1187Since nowadays most systems are PCI centric, the data structures used 1188are tuned towards (onboard and expansion bus) PCI devices. Each driver 1189consists of at least two structures. 1190 1191The \texttt{pci\_driver} structure maps PCI vendor/device id pairs to a 1192second structure that describes a set of functions that together 1193initialize and operate the device: 1194 1195\begin{verbatim} 1196 static void adaptec_scsi_init(struct device *dev) 1197 { 1198 [..] 1199 } 1200 static struct device_operations lsi_scsi_ops = { 1201 .read_resources = pci_dev_read_resources, 1202 .set_resources = pci_dev_set_resources, 1203 .enable_resources = pci_dev_enable_resources, 1204 .init = lsi_scsi_init, 1205 .scan_bus = 0, 1206 }; 1207 static const struct pci_driver lsi_scsi_driver __pci_driver = { 1208 .ops = &lsi_scsi_ops, 1209 .vendor = 0xXXXX, 1210 .device = 0xXXXX, 1211 }; 1212\end{verbatim} 1213 1214By separating the two structures above, M:N relations between compatible 1215devices and drivers can be described. The driver source code containing 1216above data structures and code have to be added to a coreboot image 1217using the driver keyword in the mainboard specific configuration file \\ 1218\texttt{coreboot-v2/src/mainboard/<vendor>/<mainboard>/Config.lb}: 1219 1220\begin{verbatim} 1221 driver lsi_scsi.o 1222\end{verbatim} 1223 1224\subsection{Bus Bridges} 1225 1226Currently all bridges supported in the coreboot-v2 tree are transparent 1227bridges. This means, once the bridge is initialized, it's remote devices 1228are visible on one of the PCI buses without special probing. coreboot 1229supports also bridges that are nontransparent. The driver support code 1230can provide a \texttt{scan\_bus} function to scan devices behind the bridge. 1231 1232\subsection{CPU Reset} 1233When changing speed and width of hypertransport chain connections 1234coreboot has to either assert an LDTSTOP or a reset to make the changes 1235become active. Additionally Linux can do a firmware reset, if coreboot 1236provides the needed infrastructure. To use this capability, define the 1237option \texttt{CONFIG\_HAVE\_HARD\_RESET} and add an object file specifying the 1238reset code in your mainboard specific configuration file 1239\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/Config.lb}: 1240 1241\begin{verbatim} 1242 default CONFIG_HAVE_HARD_RESET=1 1243 object reset.o 1244\end{verbatim} 1245 1246The C source file \texttt{reset.c} (resulting in \texttt{reset.o} 1247during compilation) shall define the following function to take care 1248of the system reset: 1249 1250\begin{verbatim} 1251 void hard_reset(void); 1252\end{verbatim} 1253 1254See \texttt{coreboot-v2/src/mainboard/arima/hdama/reset.c} for an example 1255implementation. 1256 1257\newpage 1258 1259% 1260% 11. coreboot Internals 1261% 1262 1263\section{coreboot Internals} 1264This chapter covers some of the internal structures and algorithms of 1265coreboot that have not been mentioned so far. 1266 1267\subsection{Code Flow} 1268 1269\begin{figure}[htb] 1270\centering 1271\includegraphics[scale=0.7]{codeflow.pdf} 1272\caption{coreboot rough Code Flow} 1273\label{fix:codeflow} 1274\end{figure} 1275 1276\newpage 1277 1278\subsection{Fallback mechanism} 1279coreboot provides a mechanism to pack two different coreboot builds 1280within one coreboot ROM image. Using the system CMOS memory coreboot 1281determines whether the last boot with a default image succeeded and 1282boots a failsafe image on failure. This allows insystem testing without 1283the risk to render the system unusable. See 1284\texttt{coreboot-v2/src/mainboard/arima/hdama/failover.c} for example 1285code. The fallback mechanism can be used with the \texttt{cmos\_util}. 1286 1287\subsection{(Un) Supported Standards} 1288coreboot supports the following standards 1289\begin{itemize} 1290\item Multiprocessing Specification (MPSPEC) 1.4 1291\item IRQ Tables (PIRQ) 1292\item ACPI (initial support on AMD64) 1293\item Elf Booting 1294\end{itemize} 1295However, the following standards are not supported until now, and will 1296probably not be supported in future revisions: 1297\begin{itemize} 1298\item APM 1299\end{itemize} 1300 1301\subsection{coreboot table} 1302coreboot stores information about the system in a data structure called 1303the coreboot table. This table can be read under Linux using the tool 1304nvramtool from the Lawrence Livermore National Laboratory. 1305 1306Get more information about lxbios and the utility itself at 1307\url{http://www.llnl.gov/linux/lxbios/lxbios.html} 1308 1309\subsection{ROMCC limitations} 1310ROMCC, part of the coreboot project, is a C compiler that translates to 1311completely rommable code. This means the resulting code does not need 1312any memory to work. This is one of the major improvements in coreboot 1313V2, since it allows almost all code to be written in C. DRAM 1314initialization can be factored and reused more easily among mainboards 1315and platforms. 1316 1317Since no memory is available during this early initialization point, 1318romcc has to map all used variables in registers for the time being. 1319Same applies for their stack usage. Generally the less registers are 1320used up by the algorithms, the better code can be factored, resulting in 1321a smaller object size. Since getting the best register usage is an NP 1322hard problem, some heuristics are used to get reasonable translation 1323time. If you run out of registers during compilation, try to refactor 1324your code. 1325 1326\subsection{CMOS handling} 1327coreboot can use the mainboard's CMOS memory to store information 1328defined in a data structure called the CMOS table . This information 1329contains serial line speed, fallback boot control, output verbosity, 1330default boot device, ECC control, and more. It can be easily enhanced by 1331enhancing the CMOS table. This table, if present, is found at 1332\texttt{coreboot-v2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/cmos.layout}. 1333It describes the available options, their possible values and their 1334position within the CMOS memory. The layout file looks as follows: 1335\begin{verbatim} 1336 # startbit length config configID name 1337 [..] 1338 392 3 e 5 baud_rate 1339 [..] 1340 1341 # configid value human readable description 1342 5 0 115200 1343 5 1 57600 1344 5 2 38400 1345 5 3 19200 1346 5 4 9600 1347 5 5 4800 1348 5 6 2400 1349 5 7 1200 1350 1351\end{verbatim} 1352 1353To change CMOS values from a running Linux system, use the 1354\texttt{cmos\_util}, provided by Linux Networks as part of the coreboot 1355utilities suite. Get it at 1356\textit{ftp://ftp.lnxi.com/pub/linuxbios/utilities/} 1357 1358\subsection {Booting Payloads} 1359coreboot can load a payload binary from a Flash device or IDE. This 1360payload can be a boot loader, like FILO or Etherboot, a kernel image, or 1361any other static ELF binary. 1362 1363To create a Linux kernel image, that is bootable in coreboot, you have 1364to use mkelfImage. The command line I used, looks like follows: 1365 1366\begin{verbatim} 1367 objdir/sbin/mkelfImage t bzImagei386 kernel /boot/vmlinuz \ 1368 commandline="console=ttyS0,115200 root=/dev/hda3" \ 1369 initrd=/boot/initrd output vmlinuz.elf 1370\end{verbatim} 1371 1372 1373This will create the file \texttt{vmlinuz.elf} from a distribution 1374kernel, console redirected to the serial port and using an initial 1375ramdisk. 1376 1377\subsection{Kernel on dhcp/tftp} 1378 1379One possible scenario during testing is that you keep your kernel (or 1380any additional payload) on a different machine on the network. This can 1381quickly be done using a DHCP and TFTP server. 1382 1383Use for example following \texttt{/etc/dhcpd.conf} (adapt to your 1384network): 1385 1386\begin{verbatim} 1387 subnet 192.168.1.0 netmask 255.255.255.0 { 1388 range 192.168.1.0 192.168.1.31; 1389 option broadcastaddress 192.168.1.255; 1390 } 1391 1392 ddnsupdatestyle adhoc; 1393 1394 host hammer12 { 1395 hardware ethernet 00:04:76:EA:64:31; 1396 fixedaddress 192.168.1.24; 1397 filename "vmlinuz.elf"; 1398 } 1399\end{verbatim} 1400 1401 1402Additionally you have to run a \texttt{tftp} server. You can start one 1403using \texttt{inetd}. To do this, you have to remove the comment from 1404the following line in \texttt{/etc/inetd.conf}: 1405 1406\begin{verbatim} 1407 tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot 1408\end{verbatim} 1409 1410Then put your kernel image \texttt{vmlinuz.elf} in \texttt{/tftpboot} on 1411the \texttt{tftp} server. 1412 1413 1414\newpage 1415 1416% 1417% 12. Advanced Device Initialization Mechanisms 1418% 1419 1420\section{Advanced Device Initialization Mechanisms} 1421 1422Like software, today's hardware is getting more and more complex. To 1423stay flexible many hardware vendors start breaking hardware 1424compatibility to old standards like VGA. Thus, VGA is still supported by 1425most cards, but emulation has to be enabled by the firmware for the 1426device to operate properly. Also, many expansion cards are small 1427discrete systems that have to initialize attached ram, download 1428controller firmware and similar. Without this initialization, an 1429operating system can not take advantage of the hardware, so there needs 1430to be a way to address this issue. There are several alternatives: 1431 1432\subsection{Native coreboot Support} 1433 1434For some devices (ie Trident Cyberblade 3d) there is native coreboot 1435support This means there is a small driver bound to the PCI id of the 1436device that is called after PCI device ressources are allotted. 1437 1438PROs: 1439 \begin{itemize} 1440 \item open source 1441 \item minimal driver 1442 \item early control 1443 \end{itemize} 1444 1445CONs: 1446 \begin{itemize} 1447 \item need an additional driver 1448 \item viable for onboard devices only 1449 \item not flexible for pci cards 1450 \end{itemize} 1451 1452\subsection{Using Native Linux Support} 1453 1454A simple way of getting a whole lot of drivers available for coreboot 1455is to reuse Linux drivers by putting a Linux kernel to flash. This 1456works, because no drivers are needed to get the Linux kernel (as opposed 1457to store the kernel on a harddisk connected to isa/scsi/raid storage) 1458 1459PROs: 1460 \begin{itemize} 1461 \item large number of open source drivers 1462 \end{itemize} 1463 1464CONs: 1465 \begin{itemize} 1466 \item need Linux in Flash (BLOAT!) 1467 \item drivers expect devices to be initialized (LSI1020/1030) 1468 \item Linux only 1469 \item large flash needed (4MBit minimum, normal operations 8+ MBit) 1470 \end{itemize} 1471 1472 1473\subsection{Running X86 Option ROMs} 1474 1475Especially SCSI/RAID controllers and graphics adapters come with a 1476special option rom. This option rom usually contains x86 binary code 1477that uses a legacy PCBIOS interface for device interaction. If this code 1478gets executed, the device becomes operable in Linux and other operating 1479systems. 1480 1481PROs: 1482 \begin{itemize} 1483 \item really flexible 1484 \item no need for additional drivers on firmware layer 1485 \item large number of supported devices 1486 \end{itemize} 1487 1488CONs: 1489 \begin{itemize} 1490 \item non-x86 platforms need complex emulation 1491 \item x86 platforms need legacy API 1492 \item outdated concept 1493 \end{itemize} 1494 1495 1496\subsection{Running Open Firmware Option ROMs} 1497 1498Some PCI devices come with open firmware option roms. These devices are 1499normally found in computers from SUN, Apple or IBM. Open Firmware is a 1500instruction set architecture independent firmware standard that allows 1501device specific initialization using simple, small, but flexible 1502bytecode that runs with minimal footprint on all architectures that have 1503an Open Firmware implementation. 1504 1505There is a free Open Firmware implementation available, called OpenBIOS, 1506that runs on top of coreboot. See www.openbios.org 1507 1508PROs: 1509 \begin{itemize} 1510 \item architecture independence 1511 \item small footprint 1512 \item clean concept, less bugs 1513 \end{itemize} 1514 1515CONs: 1516 \begin{itemize} 1517 \item only small number of devices come with OpenFirmware capable option roms 1518 \end{itemize} 1519 1520% 1521% 13 image types 1522% 1523 1524\section{Image types} 1525There 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 1526was changed to coreboot, for many reasons. Second, Cache As Ram support (CAR) 1527was 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. 1528 1529There are two big additions to the build process and, furthermore, more than two new CONFIG variables to control them. 1530 1531\begin{itemize} 1532\item \begin{verbatim}CONFIG_USE_DCACHE_RAM\end{verbatim} 1533 1534Set to \texttt{1} to use Cache As Ram (CAR). Defaults to \texttt{0} 1535 1536\end{itemize} 1537 1538Before going over the new image types, derived from v3, we will quickly review the standard v2 image types. We are hoping this review will 1539aid comprehension. 1540 1541A 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. 1542 1543\subsection{romcc images (from emulation/qemu)} 1544ROMCC 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 1545one 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. 1546\subsubsection{How it is built} 1547Romcc 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. 1548 1549File for the ram part are compiled in a conventional manner. 1550 1551The 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: 1552\begin{verbatim} 1553 [Nr] Name Type Addr Off Size ES Flg Lk Inf Al 1554 [ 0] NULL 00000000 000000 000000 00 0 0 0 1555 [ 1] .ram PROGBITS ffff0000 001000 005893 00 WA 0 0 1 1556 [ 2] .rom PROGBITS ffff5893 006893 00029d 00 AX 0 0 16 1557 [ 3] .reset PROGBITS fffffff0 006ff0 000010 00 A 0 0 1 1558 [ 4] .id PROGBITS ffffffd1 006fd1 00001f 00 A 0 0 1 1559 [ 5] .shstrtab STRTAB 00000000 007000 000030 00 0 0 1 1560 [ 6] .symtab SYMTAB 00000000 007170 000c30 10 7 37 4 1561 [ 7] .strtab STRTAB 00000000 007da0 000bfd 00 0 0 1 1562\end{verbatim} 1563 1564The only sections that get loaded into a ROM are the Allocated ones. We can see the .ram, .rom, .reset and .id sections. 1565\subsubsection{layout} 1566As 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. 1567 1568\begin{itemize} 1569\item CONFIG\_PAYLOAD\_SIZE. Each image may have a different payload size. 1570\item CONFIG\_ROMBASE Each image must have a different base in rom. 1571\item CONFIG\_RESET Unclear what this is used for. 1572\item CONFIG\_EXCEPTION\_VECTORS where an optional IDT might go. 1573\item CONFIG\_USE\_OPTION\_TABLE if set, an option table section will be linked in. 1574\item CONFIG\_ROM\_PAYLOAD\_START This is the soon-to-be-deprecated way of locating a payload. cbfs eliminates this. 1575\item CONFIG\_USE\_FALLBACK\_IMAGE Whether this is a fallback or normal image 1576\item CONFIG\_ROM\_SECTION\_SIZE Essentially, the payload size. Soon to be deprecated. 1577\item CONFIG\_ROM\_IMAGE\_SIZE Size of this image (i.e. fallback or normal image) 1578\item CONFIG\_ROM\_SIZE Total size of the ROM 1579\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. 1580\end{itemize} 1581 1582Each 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. 1583 1584\subsubsection{boot sequence} 1585We 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. 1586 1587If 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: 1588\begin{verbatim} 1589 /* This is the primary cpu how should I boot? */ 1590 else if (do_normal_boot()) { 1591 goto normal_image; 1592 } 1593 else { 1594 goto fallback_image; 1595 } 1596 normal_image: 1597 __asm__ volatile ("jmp __normal_image" 1598 : /* outputs */ 1599 : "a" (bist), "b" (cpu_init_detectedx) /* inputs */ 1600 ); 1601 1602 fallback_image: 1603#if CONFIG_HAVE_FAILOVER_BOOT==1 1604 __asm__ volatile ("jmp __fallback_image" 1605 : /* outputs */ 1606 : "a" (bist), "b" (cpu_init_detectedx) /* inputs */ 1607 ) 1608#endif 1609 ; 1610\end{verbatim} 1611How 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. 1612Finally, we can see this in the Config.lb for most mainboards: 1613\begin{verbatim} 1614if CONFIG_USE_FALLBACK_IMAGE 1615 mainboardinit cpu/x86/16bit/reset16.inc 1616 ldscript /cpu/x86/16bit/reset16.lds 1617else 1618 mainboardinit cpu/x86/32bit/reset32.inc 1619 ldscript /cpu/x86/32bit/reset32.lds 1620end 1621\end{verbatim} 1622What 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. 1623\subsection{car images (from lippert/roadrunner-lx)} 1624CAR 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. 1625\subsubsection{How it is built} 1626The 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}. 1627\subsubsection{layout} 1628No significant change from romcc code. 1629\subsubsection{boot sequence} 1630No significant change from romcc code, except that the CAR code has to set up a stack. 1631 1632\subsection{car + CONFIG\_USE\_INIT images (new emulation/qemu} 1633This type of image makes more use of the C compiler. In this type of image, in fact, 1634seperate 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. 1635\subsubsection{How it is built} 1636There 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. 1637\subsubsection{layout} 1638No significant change from romcc code. 1639\subsubsection{boot sequence} 1640No significant change from romcc code, except that the CAR code has to set up a stack. 1641 1642\subsubsection{layout} 1643No significant change from romcc code. 1644\subsubsection{boot sequence} 1645No significant change from romcc code, except that the CAR code has to set up a stack. 1646\subsection{failover} 1647Failover 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: 1648\begin{verbatim} 1649static unsigned long main(unsigned long bist) 1650{ 1651 if (do_normal_boot()) 1652 goto normal_image; 1653 else 1654 goto fallback_image; 1655 1656normal_image: 1657 __asm__ __volatile__("jmp __normal_image" : : "a" (bist) : ); 1658 1659cpu_reset: 1660 __asm__ __volatile__("jmp __cpu_reset" : : "a" (bist) : ); 1661 1662fallback_image: 1663 return bist; 1664} 1665 1666\end{verbatim} 1667Some 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: 1668\begin{quote} 1669./src/mainboard/iei/nova4899r/failover.c 1670./src/mainboard/emulation/qemu-x86/failover.c 1671./src/mainboard/supermicro/x6dhr\_ig/failover.c 1672./src/mainboard/supermicro/x6dai\_g/failover.c 1673./src/mainboard/supermicro/x6dhe\_g2/failover.c 1674./src/mainboard/supermicro/x6dhr\_ig2/failover.c 1675./src/mainboard/supermicro/x6dhe\_g/failover.c 1676./src/mainboard/dell/s1850/failover.c 1677./src/mainboard/intel/xe7501devkit/failover.c 1678./src/mainboard/intel/jarrell/failover.c 1679./src/mainboard/olpc/btest/failover.c 1680./src/mainboard/olpc/rev\_a/failover.c 1681./src/mainboard/via/epia-m/failover.c 1682\end{quote} 1683Here is one of the more complicated ones: 1684\begin{verbatim} 1685static unsigned long main(unsigned long bist) 1686{ 1687 /* Did just the cpu reset? */ 1688 if (memory_initialized()) { 1689 if (last_boot_normal()) { 1690 goto normal_image; 1691 } else { 1692 goto cpu_reset; 1693 } 1694 } 1695 1696 /* This is the primary cpu how should I boot? */ 1697 else if (do_normal_boot()) { 1698 goto normal_image; 1699 } 1700 else { 1701 goto fallback_image; 1702 } 1703 normal_image: 1704 asm volatile ("jmp __normal_image" 1705 : /* outputs */ 1706 : "a" (bist) /* inputs */ 1707 : /* clobbers */ 1708 ); 1709 cpu_reset: 1710 asm volatile ("jmp __cpu_reset" 1711 : /* outputs */ 1712 : "a"(bist) /* inputs */ 1713 : /* clobbers */ 1714 ); 1715 fallback_image: 1716 return bist; 1717} 1718 1719\end{verbatim} 1720They'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. 1721\subsubsection{How it is built} 1722There two additional config variables: 1723\begin{itemize} 1724\item HAVE\_FAILOVER\_IMAGE Has to be defined when certain files are included. 1725\item USE\_FAILOVER\_IMAGE Enables the use of the failover image 1726\end{itemize} 1727Confusingly enough, almost all the uses of these two variables are either nested or both required to be set, e.g. 1728The fallback and normal builds are the same. The target config has a new clause that looks like this: 1729\begin{verbatim} 1730romimage "failover" 1731 option CONFIG_USE_FAILOVER_IMAGE=1 1732 option CONFIG_USE_FALLBACK_IMAGE=0 1733 option CONFIG_ROM_IMAGE_SIZE=CONFIG_FAILOVER_SIZE 1734 option CONFIG_XIP_ROM_SIZE=CONFIG_FAILOVER_SIZE 1735 option COREBOOT_EXTRA_VERSION="\$(shell cat ../../VERSION)\_Failover" 1736end 1737\end{verbatim} 1738This new section uses some constructs not yet discussed in detail. XIP\_ROM\_SIZE just refers to the 1739fact 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: 1740\begin{verbatim} 1741src/cpu/amd/car/cache_as_ram.inc 1742src/arch/i386/Config.lb 1743\end{verbatim} 1744For the cache\_as\_ram.inc file, the changes relate to the fact that failover code sets up CAR, so that fallback code need not. 1745 1746For the Config.lb, several aspects of build change. 1747When 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). 1748\subsubsection{layout} 1749Failover.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. 1750\subsubsection{boot sequence} 1751failover.c tests a few variables and the calls the normal or fallback payload depending on those variables; usually they are CMOS settings. 1752\subsection{Proposed new image forat} 1753The new image format will use seperate compilation -- no C code included! -- on all files. 1754 1755The new design has a few key goals: 1756\begin{itemize} 1757\item Always use a bootblock (currently called failover). 1758The 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. 1759\item Always use seperate compilation 1760\item Always use printk etc. in the ROM code 1761\item (longer term) from the bootblock, always use cbfs to locate the normal/fallback etc. code. This code will be XIP. 1762\end{itemize} 1763 1764\subsubsection{How it is built} 1765For 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. 1766\subsubsection{layout} 1767Almost the same, for now, as the current failover code. 1768\subsubsection{boot sequence} 1769% 1770% 14 Glossary 1771% 1772 1773\section{Glossary} 1774\begin{itemize} 1775\item payload 1776 1777coreboot only cares about low level machine initialization, but also has 1778very simple mechanisms to boot a file either from FLASHROM or IDE. That 1779file, possibly a Linux Kernel, a boot loader or Etherboot, are called 1780payload, since it is the first software executed that does not cope with 1781pure initialization. 1782 1783\item flash device 1784 1785Flash devices are commonly used in all different computers since unlike 1786ROMs they can be electronically erased and reprogrammed. 1787\end{itemize} 1788 1789\newpage 1790 1791% 1792% 14 Bibliography 1793% 1794 1795\section{Bibliography} 1796\subsection{Additional Papers on coreboot} 1797 1798\begin{itemize} 1799 \item 1800 \textit{\url{http://www.coreboot.org/Documentation}} 1801 \item 1802 \textit{\url{http://www.lysator.liu.se/upplysning/fa/linuxbios.pdf}} 1803 \item 1804 \textit{\url{http://portal.acm.org/citation.cfm?id=512627}} 1805\end{itemize} 1806 1807\subsection {Links} 1808 1809\begin{itemize} 1810 \item Etherboot: \textit{\url{http://www.etherboot.org/}} 1811 \item Filo: \textit{\url{http://www.coreboot.org/FILO}} 1812 \item OpenBIOS: \textit{\url{http://www.openbios.org/}} 1813\end{itemize} 1814 1815\end{document} 1816