/ Documentation / corebootBuildingGuide.tex
corebootBuildingGuide.tex
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{epsfig} 10 \usepackage{epstopdf} 11 \usepackage{url} 12 \usepackage{color} 13 % \usepackage{geometry} 14 \usepackage[pdftex]{hyperref} 15 % \usepackage{makeidx} 16 % \makeindex 17 % \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm} 18 19 \hypersetup{ 20 urlbordercolor={1 1 1}, 21 menubordercolor={1 1 1}, 22 linkbordercolor={1 1 1}, 23 colorlinks=false, 24 % pdfpagemode=None, % PDF-Viewer starts without TOC 25 % pdfstartview=FitH, 26 pdftitle={coreboot Porting Guide}, 27 pdfauthor={Zheng Bao}, 28 pdfsubject={coreboot configuration and build process}, 29 pdfkeywords={coreboot, AMD, configuration, Build} 30 } 31 32 \setlength{\parindent}{0pt} 33 \setlength{\hoffset}{0pt} 34 35 \title{coreboot from Scratch} 36 \author{Stefan Reinauer $<$stepan@coresystems.de$>$\and Zheng Bao $<$zheng.bao@amd.com$>$} 37 \date{Dec 4th, 2013} 38 39 \begin{document} 40 41 \maketitle 42 43 \thispagestyle{empty} 44 45 \tableofcontents 46 47 \newpage 48 49 \section{What is coreboot} 50 coreboot aims to replace the normal BIOS found on x86, AMD64, PPC, 51 Alpha, and other machines with a Linux kernel that can boot Linux from a cold 52 start. The startup code of an average coreboot port is about 500 lines of 53 assembly and 5000 lines of C. It executes 16 instructions to get into 32bit 54 protected mode and then performs DRAM and other hardware initializations 55 required before Linux can take over. 56 57 The projects primary motivation initially was maintenance of large 58 clusters. Not surprisingly interest and contributions have come from 59 people with varying backgrounds. Nowadays a large and growing number of 60 Systems can be booted with coreboot, including embedded systems, 61 Desktop PCs and Servers. 62 63 This document is used to build, modify, and port the coreboot code 64 base on the AMD platform. 65 66 67 \section{Changes} 68 69 \begin{itemize} 70 \item 2013/12/20 Add Git, Gerrit, toolchains building. 71 \item 2009/04/19 replace LinuxBIOS with coreboot 72 \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ 73 \item 2004/02/10 ACPI and option ROM updates 74 \item 2003/11/18 initial release 75 \end{itemize} 76 77 % 78 % Build Requirements 79 % 80 81 \section{Build Requirements} 82 To build coreboot for AMD64 from the sources you need a recent Linux. 83 SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD, 84 NetBSD are known to work fine. 85 86 To build the toolchain, you need following host compilers: 87 88 \begin{itemize} 89 \item GNUtar 90 \item GNUpatch 91 \item GNUmake 92 \item GCC 93 \item binutils 94 \item bison 95 \item flex 96 \item m4 97 \item wget 98 \end{itemize} 99 100 Besides the tools above, after the toolchains are built, you also need the following 101 tools to build the source. 102 103 \begin{itemize} 104 \item git: Get the source code from repository 105 \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig 106 \item python: Optional for gdb. 107 \item perl: Optional for gdb. 108 \end{itemize} 109 110 % 111 % Getting coreboot 112 % 113 114 \section{Getting coreboot} 115 The latest coreboot sources are available via GIT. 116 For users who doesn't need to change and commit the code: 117 { \small 118 \begin{verbatim} 119 $ git clone https://review.coreboot.org/coreboot 120 \end{verbatim} 121 } 122 For developers, you need to get a gerrit account which you can register 123 at \url{https://review.coreboot.org}. Please refer section ~\ref{sec:gerrit} 124 { \small 125 \begin{verbatim} 126 $ git clone ssh://<username>@review.coreboot.org:29418/coreboot 127 $ git clone https://[<username>:<password>@]review.coreboot.org/coreboot.git 128 \end{verbatim} 129 } 130 131 Checks out a sub-repository in the 3rdparty directory. 132 { \small 133 \begin{verbatim} 134 $ git submodule update --init --checkout 135 \end{verbatim} 136 } 137 138 % 139 % Building the toolchain 140 % 141 142 \section{Building the toolchain} 143 coreboot recommends and guarantees the toolchain integrated with coreboot. 144 Linux distributions usually modify their compilers in ways incompatible with coreboot. 145 146 { \small 147 \begin{verbatim} 148 $ cd coreboot 149 $ make crossgcc 150 \end{verbatim} 151 } 152 153 or 154 155 { \small 156 \begin{verbatim} 157 $ cd util/crossgcc 158 $ buildgcc 159 \end{verbatim} 160 } 161 162 The buildgcc will try to get packages from website. You need to make sure you can 163 get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs. 164 165 { \small 166 \textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)} 167 168 Target arch is now i386-elf 169 170 Will skip GDB ... ok 171 172 Downloading tar balls ... 173 174 * gmp-5.1.2.tar.bz2 (cached) 175 176 * mpfr-3.1.2.tar.bz2 (cached) 177 178 * mpc-1.0.1.tar.gz (cached) 179 180 * libelf-0.8.13.tar.gz (cached) 181 182 * gcc-4.7.3.tar.bz2 (cached) 183 184 * binutils-2.23.2.tar.bz2 (cached) 185 186 * acpica-unix-20130626.tar.gz (cached) 187 188 Downloaded tar balls ... \textcolor {green}{ok} 189 190 Unpacking and patching ... 191 192 * gmp-5.1.2.tar.bz2 193 194 * mpfr-3.1.2.tar.bz2 195 196 * mpc-1.0.1.tar.gz 197 198 * libelf-0.8.13.tar.gz 199 200 * gcc-4.7.3.tar.bz2 201 202 * binutils-2.23.2.tar.bz2 203 204 o binutils-2.23.2\_arv7a.patch 205 206 o binutils-2.23.2\_no-bfd-doc.patch 207 208 * acpica-unix-20130626.tar.gz 209 210 Unpacked and patched ... \textcolor {green}{ok} 211 212 Building GMP 5.1.2 ... \textcolor {green}{ok} 213 214 Building MPFR 3.1.2 ... \textcolor {green}{ok} 215 216 Building MPC 1.0.1 ... \textcolor {green}{ok} 217 218 Building libelf 0.8.13 ... \textcolor {green}{ok} 219 220 Building binutils 2.23.2 ... \textcolor {green}{ok} 221 222 Building GCC 4.7.3 ... ok 223 224 Skipping Expat (Python scripting not enabled) 225 226 Skipping Python (Python scripting not enabled) 227 228 Skipping GDB (GDB support not enabled) 229 230 Building IASL 20130626 ... \textcolor {green}{ok} 231 232 Cleaning up... \textcolor {green}{ok} 233 234 \textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.} 235 } 236 If you are lucky, you can get toolchains located in util/crossgcc/xgcc. 237 238 % 239 % Build coreboot 240 % 241 242 \section{Building coreboot} 243 \subsection{Build main module of coreboot} 244 { \small 245 \begin{verbatim} 246 $ cd coreboot 247 $ make menuconfig 248 .config - coreboot v4.0-4895-gc5025a4-dirty Configuration 249 +------------------------ coreboot Configuration -------------------------+ 250 | Arrow keys navigate the menu. <Enter> selects submenus --->. | 251 | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | 252 | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | 253 | for Search. Legend: [*] built-in [ ] excluded <M> module < > | 254 | +---------------------------------------------------------------------+ | 255 | | General setup ---> | | 256 | | Mainboard ---> | | 257 | | Architecture (x86) ---> | | 258 | | Chipset ---> | | 259 | | Devices ---> | | 260 | | VGA BIOS ---> | | 261 | | Display ---> | | 262 | | PXE ROM ---> | | 263 | | Generic Drivers ---> | | 264 | | Console ---> | | 265 | | [ ] Relocatable Modules | | 266 | | System tables ---> | | 267 | | Payload ---> | | 268 | | Debugging ---> | | 269 | | --- | | 270 | +----v(+)-------------------------------------------------------------+ | 271 +-------------------------------------------------------------------------+ 272 | <Select> < Exit > < Help > | 273 +------------------------------------------------------------------------- 274 \end{verbatim} 275 } 276 Select Mainboard -$>$ Mainboard Vendor -$>$ AMD 277 -$>$ Mainboard Model -$>$ Olive Hill 278 279 Then save, exit and run make. 280 281 { \small 282 \begin{verbatim} 283 $ make 284 \end{verbatim} 285 } 286 The built image, coreboot.rom, is located at folder build. 287 288 \section{Programming coreboot to flash memory} 289 The image resulting from a coreboot build can be directly programmed to 290 a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the 291 Linux flash utility, flashrom. 292 293 294 \subsection{Add modules and payload} 295 296 \subsubsection{VGA BIOS} 297 There is a big Chance that you need to get a VGA BIOS. 298 { \small 299 \begin{verbatim} 300 .config - coreboot v4.0 Configuration 301 ------------------------------------------------------------------------------ 302 +-------------------------------- VGA BIOS --------------------------------+ 303 | Arrow keys navigate the menu. <Enter> selects submenus --->. | 304 | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | 305 | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | 306 | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | 307 | +----------------------------------------------------------------------+ | 308 | | [*] Add a VGA BIOS image | | 309 | | (vgabios.bin) VGA BIOS path and filename | | 310 | | (1002,1306) VGA device PCI IDs | | 311 | | | | 312 | | | | 313 | | | | 314 | | | | 315 | | | | 316 | | | | 317 | +----------------------------------------------------------------------+ | 318 +--------------------------------------------------------------------------+ 319 | <Select> < Exit > < Help > | 320 +--------------------------------------------------------------------------+ 321 \end{verbatim} 322 } 323 Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the 324 Option ROM from Vendor's website. 325 326 \subsubsection{Payload} 327 coreboot in itself is "only" minimal code for initializing a mainboard 328 with peripherals. After the initialization, it jumps to a payload. 329 330 Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS 331 is setting it in menuconfig. 332 { \small 333 \begin{verbatim} 334 +------------------------------- Payload ---------------------------------+ 335 | Arrow keys navigate the menu. <Enter> selects submenus --->. | 336 | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | 337 | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | 338 | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | 339 | +----------------------------------------------------------------------+ | 340 | | Add a payload (SeaBIOS) ---> | | 341 | | SeaBIOS version (1.7.2.1) ---> | | 342 | | [*] Use LZMA compression for payloads (NEW) | | 343 | | | | 344 | | | | 345 | | | | 346 | | | | 347 | | | | 348 | | | | 349 | +----------------------------------------------------------------------+ | 350 +--------------------------------------------------------------------------+ 351 | <Select> < Exit > < Help > | 352 +--------------------------------------------------------------------------+ 353 \end{verbatim} 354 The script in Makefile will automatically checkout, config, build the SeaBIOS source, 355 and integrat the binary into the final image. 356 357 % 358 % Working with Git 359 % 360 361 \section{Working with Git} 362 \subsection{Configuration of Git} 363 Inside the checkout you should install a commit-msg hook that adds a 364 Change-Id into commit messages, which uniquely identifies the logical 365 change in Gerrit even across multiple iterations of the commit. The 366 hook only needs to be installed once per clone, and installation can 367 be done with: 368 { \small 369 \begin{verbatim} 370 $ cd coreboot 371 $ cp ./util/gitconfig/* .git/hooks 372 \end{verbatim} 373 } 374 configure your name and email in git. 375 { \small 376 \begin{verbatim} 377 $ git config --global user.name "Your Name Comes Here" 378 $ git config --global user.email your.email@example.com' 379 \end{verbatim} 380 } 381 The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit. 382 Otherwise you can not push you code to community. 383 384 Then run the following command once, to tell git that by default you 385 want to submit all commits in the currently checked-out branch for 386 review on gerrit: 387 { \small 388 \begin{verbatim} 389 $ git config remote.origin.push HEAD:refs/for/main 390 \end{verbatim} 391 } 392 393 The above configurations for git has been integrated into Makefile. You can run 394 { \small 395 \begin{verbatim} 396 $ make gitconfig 397 \end{verbatim} 398 } 399 400 \subsection{Work flow} 401 402 It is recommended that you make a new branch when you start to work, not pushing changes to main. 403 { \small 404 \begin{verbatim} 405 $ git checkout main -b mybranch 406 \end{verbatim} 407 } 408 After you have done your changes, run: 409 { \small 410 \begin{verbatim} 411 $ git add file_need_to_submit.c 412 $ git commit -m "my first change." 413 \end{verbatim} 414 } 415 416 % Does anyone have a better word to describe the philosophy of splitting changes to patches? 417 You need to realize that the changes you have made should be well divided into 418 several commits. Each of them has one and only one meaning. You could use git rebase -i to 419 split, squash, remove, rewrite you comment. 420 421 Here is an example of a well-formatted commit message: 422 423 { \small 424 \begin{verbatim} 425 examplecomponent: Refactor duplicated setup into a function 426 427 Setting up the demo device correctly requires the exact same register 428 values to be written into each of the PCI device functions. Moving the 429 writes into a function allows also otherexamplecomponent to use them. 430 431 Signed-off-by: Joe Hacker <joe@hacker.email> 432 \end{verbatim} 433 } 434 435 Then you can push the code. 436 { \small 437 \begin{verbatim} 438 $ git push 439 \end{verbatim} 440 } 441 442 You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed. 443 444 Often it might happen that the patch you sent for approval is not good 445 enough from the first attempt. Gerrit and git make it easy to track 446 patch evolution during the review process until patches meet our 447 quality standards and are ready for approval. 448 449 You can easily modify a patch sent to gerrit by you or even by someone 450 else. Just apply it locally using one of the possible ways to do it, 451 make a new local commit that fixes the issues reported by the 452 reviewers, then rebase the change by preserving the same Change-ID. We 453 recommend you to use the git rebase command in interactive mode, 454 455 Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/main. 456 457 % 458 % Working with Gerrit 459 % 460 461 \section{Working with Gerrit} 462 \label{sec:gerrit} 463 If you are a coreboot user, not planning to contribute, you can skip this section. 464 \subsection{Get gerrit account} 465 You need to get an OpenID first. Currently Google account give you an OpenID. It means, if you have a gmail account, you have an OpenID. You can try to signed in. 466 click \url{https://review.coreboot.org} 467 468 %\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png} 469 { \small 470 \begin{verbatim} 471 +-----------------------------------------------------------+ 472 |All Projects Documentation Register Sign In | 473 |Open Merged Abandoned | 474 |Search for status:open | 475 +-----------------------------------------------------------+ 476 |Subject Status Owner Project Branch Updated CR V | 477 |cpu: Rename.. Alexandru coreboot main 1:20 PM +1 | 478 |cpu: Only a.. Alexandru coreboot main 1:17 PM X | 479 |arch/x86: D.. Alexandru coreboot main 1:09 PM | 480 | | 481 | Next -> | 482 |Press '?' to view keyboard shortcuts | Powered by Gerrit | 483 +-----------------------------------------------------------+ 484 \end{verbatim} 485 } 486 Click ``Sign In'', You will get 487 488 %\includegraphics[width=6.00in,height=4.00in]{openid.png} 489 490 You will be redirected to Google to get logging in. 491 492 % \includegraphics[width=6.00in,height=1.50in]{login.png} 493 { \small 494 \begin{verbatim} 495 Sign In to Gerrit Code Review at review.coreboot.org 496 +--------------------------------------------------+ 497 +--------------------------------------------------+ 498 [] Remember me 499 Sign In Cancel 500 Sign in with a Google Account 501 Sign in with a Yahoo! ID 502 What is OpenID? 503 504 OpenID provides secure single-sign-on, without revealing your passwords to this website. 505 506 There are many OpenID providers available. You may already be member of one! 507 508 Get OpenID 509 \end{verbatim} 510 } 511 512 \subsection{Configure account} 513 Click the dropdown button near the user name and click ``Settings'' 514 515 % \includegraphics[width=6.00in,height=4.00in]{settings} 516 % \epsfig{figure=keystroke_left} 517 % \epstopdf {file=settings.eps} 518 % \epsfig{file=settings.eps} 519 520 \label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once. 521 { \small 522 \begin{verbatim} 523 Profile Username zbao 524 Preferences Full Name Zheng Bao 525 Watched Projects Email Address zheng.bao@amd.com 526 Contact Information Registered Jun 28, 2011 4:33 PM 527 SSH Public Keys Account ID 1000034 528 HTTP Password 529 Identities 530 Groups 531 \end{verbatim} 532 } 533 534 \label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig 535 { \small 536 \begin{verbatim} 537 Full Name __________________________________ 538 Preferred Email ______________ Registered Email 539 540 Save Changes 541 \end{verbatim} 542 } 543 544 In ``SSH Public Keys'' section, upload your public key. 545 { \small 546 \begin{verbatim} 547 Status Algorithm Key Comment 548 549 Delete 550 Add SSH Public Key 551 > How to Generate an SSH Key 552 +--------------------------+ 553 | | 554 | | 555 | | 556 | | 557 | | 558 | | 559 | | 560 | | 561 | | 562 +--------------------------+ 563 clear Add Close 564 \end{verbatim} 565 } 566 567 Click ``Add Key ...'' 568 Go back to you linux command line and type: 569 { \small 570 \begin{verbatim} 571 $ ssh-keygen 572 Generating public/private rsa key pair. 573 Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa): 574 Enter passphrase (empty for no passphrase): 575 Enter same passphrase again: 576 Your identification has been saved in /home/zhengbao/.ssh/id_rsa. 577 Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub. 578 The key fingerprint is: 579 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb@host.domain 580 The key's randomart image is: 581 +--[ RSA 2048]----+ 582 | | 583 | | 584 | | 585 | | 586 | | 587 | | 588 | | 589 | | 590 | | 591 +-----------------+ 592 \end{verbatim} 593 } 594 The data in ~/.ssh/id\_rsa.pub is your public key. Copy them to the box in the page of ``SSH Public Keys'' and click add. 595 596 In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout. 597 { \small 598 \begin{verbatim} 599 Username XXX 600 Password XXXXXXXXXXXX 601 602 Generate Password Clear Password 603 604 \end{verbatim} 605 } 606 607 \subsection{Reviewing Changes} 608 For each listed changes in Gerrit, you can review, comment, evaluate, 609 cherry-pick, and even re-submit them. For you own patches, only you can 610 abandon them. Click in the file and commit message, you can add in-line comment. 611 612 % 613 % 14 Glossary 614 % 615 616 \section{Glossary} 617 \begin{itemize} 618 \item payload 619 620 coreboot only cares about low level machine initialization, but also has 621 very simple mechanisms to boot a file either from FLASHROM or IDE. That 622 file, possibly a Linux Kernel, a boot loader or Etherboot, are called 623 payload, since it is the first software executed that does not cope with 624 pure initialization. 625 626 \item flash device 627 628 Flash devices are commonly used in all different computers since unlike 629 ROMs they can be electronically erased and reprogrammed. 630 631 \item Gerrit 632 633 Gerrit is a web based code review system, facilitating online code 634 reviews for projects using the Git version control system. 635 636 Gerrit makes reviews easier by showing changes in a side-by-side 637 display, and allowing inline comments to be added by any reviewer. 638 639 Gerrit simplifies Git based project maintainership by permitting any 640 authorized user to submit changes to the upstream Git repository, rather 641 than requiring all approved changes to be merged in by hand by the 642 project maintainer. This functionality enables a more centralized 643 usage of Git. 644 645 \end{itemize} 646 647 \newpage 648 649 % 650 % 14 Bibliography 651 % 652 653 \section{Bibliography} 654 \subsection{Additional Papers on coreboot} 655 656 \begin{itemize} 657 \item 658 \textit{\url{https://www.coreboot.org/Documentation}} 659 \end{itemize} 660 661 \subsection {Links} 662 663 \begin{itemize} 664 \item Etherboot: \textit{\url{http://www.etherboot.org/}} 665 \item OpenBIOS: \textit{\url{http://www.openbios.org/}} 666 \item Flashrom: \textit{\url{http://www.flashrom.org/}} 667 \item Seabios: \textit{\url{http://www.seabios.org/}} 668 \end{itemize} 669 670 671 \end{document}