% % This document is released under the GPL % Initially written by Stefan Reinauer, <stepan@coresystems.de> % \documentclass[titlepage,12pt]{article} \usepackage{a4} \usepackage{graphicx} \usepackage{epsfig} \usepackage{epstopdf} \usepackage{url} \usepackage{color} % \usepackage{geometry} \usepackage[pdftex]{hyperref} % \usepackage{makeidx} % \makeindex % \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm} \hypersetup{ urlbordercolor={1 1 1}, menubordercolor={1 1 1}, linkbordercolor={1 1 1}, colorlinks=false, % pdfpagemode=None, % PDF-Viewer starts without TOC % pdfstartview=FitH, pdftitle={Coreboot Porting Guide}, pdfauthor={Zheng Bao}, pdfsubject={coreboot configuration and build process}, pdfkeywords={coreboot, AMD, configuration, Build} } \setlength{\parindent}{0pt} \setlength{\hoffset}{0pt} \title{Coreboot from Scratch} \author{Stefan Reinauer $<$stepan@coresystems.de$>$\and Zheng Bao $<$zheng.bao@amd.com$>$} \date{Dec 4th, 2013} \begin{document} \maketitle \thispagestyle{empty} \tableofcontents \newpage \section{What is Coreboot} coreboot aims to replace the normal BIOS found on x86, AMD64, PPC, Alpha, and other machines with a Linux kernel that can boot Linux from a cold start. The startup code of an average coreboot port is about 500 lines of assembly and 5000 lines of C. It executes 16 instructions to get into 32bit protected mode and then performs DRAM and other hardware initializations required before Linux can take over. The projects primary motivation initially was maintenance of large clusters. Not surprisingly interest and contributions have come from people with varying backgrounds. Nowadays a large and growing number of Systems can be booted with coreboot, including embedded systems, Desktop PCs and Servers. This document is used to build, modify, and port the CoreBoot code base on the AMD platform. \section{Changes} \begin{itemize} \item 2013/12/20 Add Git, Gerrit, toolchains building. \item 2009/04/19 replace LinuxBIOS with coreboot \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ \item 2004/02/10 acpi and option rom updates \item 2003/11/18 initial release \end{itemize} % % Build Requirements % \section{Build Requirements} To build coreboot for AMD64 from the sources you need a recent Linux. SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD, NetBSD are known to work fine. To build the toolchain, you need following host compilers: \begin{itemize} \item GNUtar \item GNUpatch \item GNUmake \item GCC \item binutils \item bison \item flex \item m4 \item wget \end{itemize} Besides the tools above, after the toolchains are built, you also need the following tools to build the source. \begin{itemize} \item git: Get the source code from repository \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig \item python: Optional for gdb. \item perl: Optional for gdb. \end{itemize} % % Getting Coreboot % \section{Getting Coreboot} The latest coreboot sources are available via GIT. For users who doesn't need to change and commit the code: { \small \begin{verbatim} $ git clone http://review.coreboot.org/p/coreboot \end{verbatim} } For developers, you need to get a gerrit account which you can register at \url{http://review.coreboot.org}. Please refer section ~\ref{sec:gerrit} { \small \begin{verbatim} $ git clone ssh://<username>@review.coreboot.org:29418/coreboot $ git clone http://[<username>:<password>@]review.coreboot.org/coreboot.git \end{verbatim} } Checks out a sub-repository in the 3rdparty directory. { \small \begin{verbatim} $ git submodule update --init --checkout \end{verbatim} } % % Building the toolchain % \section{Building the toolchain} Coreboot recommends and guarantees the toolchain integrated with Coreboot. Linux distributions usually modify their compilers in ways incompatible with Coreboot. { \small \begin{verbatim} $ cd coreboot $ make crossgcc \end{verbatim} } or { \small \begin{verbatim} $ cd util/crossgcc $ buildgcc \end{verbatim} } The buildgcc will try to get packages from website. You need to make sure you can get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs. { \small \textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)} Target arch is now i386-elf Will skip GDB ... ok Downloading tar balls ... * gmp-5.1.2.tar.bz2 (cached) * mpfr-3.1.2.tar.bz2 (cached) * mpc-1.0.1.tar.gz (cached) * libelf-0.8.13.tar.gz (cached) * gcc-4.7.3.tar.bz2 (cached) * binutils-2.23.2.tar.bz2 (cached) * acpica-unix-20130626.tar.gz (cached) Downloaded tar balls ... \textcolor {green}{ok} Unpacking and patching ... * gmp-5.1.2.tar.bz2 * mpfr-3.1.2.tar.bz2 * mpc-1.0.1.tar.gz * libelf-0.8.13.tar.gz * gcc-4.7.3.tar.bz2 * binutils-2.23.2.tar.bz2 o binutils-2.23.2\_arv7a.patch o binutils-2.23.2\_no-bfd-doc.patch * acpica-unix-20130626.tar.gz Unpacked and patched ... \textcolor {green}{ok} Building GMP 5.1.2 ... \textcolor {green}{ok} Building MPFR 3.1.2 ... \textcolor {green}{ok} Building MPC 1.0.1 ... \textcolor {green}{ok} Building libelf 0.8.13 ... \textcolor {green}{ok} Building binutils 2.23.2 ... \textcolor {green}{ok} Building GCC 4.7.3 ... ok Skipping Expat (Python scripting not enabled) Skipping Python (Python scripting not enabled) Skipping GDB (GDB support not enabled) Building IASL 20130626 ... \textcolor {green}{ok} Cleaning up... \textcolor {green}{ok} \textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.} } If you are lucky, you can get toolchains located in util/crossgcc/xgcc. % % Build Coreboot % \section{Building Coreboot} \subsection{Build main module of Coreboot} { \small \begin{verbatim} $ cd coreboot $ make menuconfig .config - coreboot v4.0-4895-gc5025a4-dirty Configuration +------------------------ coreboot Configuration -------------------------+ | Arrow keys navigate the menu. <Enter> selects submenus --->. | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | | for Search. Legend: [*] built-in [ ] excluded <M> module < > | | +---------------------------------------------------------------------+ | | | General setup ---> | | | | Mainboard ---> | | | | Architecture (x86) ---> | | | | Chipset ---> | | | | Devices ---> | | | | VGA BIOS ---> | | | | Display ---> | | | | PXE ROM ---> | | | | Generic Drivers ---> | | | | Console ---> | | | | [ ] Relocatable Modules | | | | System tables ---> | | | | Payload ---> | | | | Debugging ---> | | | | --- | | | +----v(+)-------------------------------------------------------------+ | +-------------------------------------------------------------------------+ | <Select> < Exit > < Help > | +------------------------------------------------------------------------- \end{verbatim} } Select Mainboard -$>$ Mainboard Vendor -$>$ AMD -$>$ Mainboard Model -$>$ Olive Hill Then save, exit and run make. { \small \begin{verbatim} $ make \end{verbatim} } The built image, coreboot.rom, is located at folder build. \section{Programming coreboot to flash memory} The image resulting from a coreboot build can be directly programmed to a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the Linux flash utility, flashrom. \subsection{Add modules and payload} \subsubsection{VGA BIOS} There is a big Chance that you need to get a VGA BIOS. { \small \begin{verbatim} .config - coreboot v4.0 Configuration ------------------------------------------------------------------------------ +-------------------------------- VGA BIOS --------------------------------+ | Arrow keys navigate the menu. <Enter> selects submenus --->. | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | | +----------------------------------------------------------------------+ | | | [*] Add a VGA BIOS image | | | | (vgabios.bin) VGA BIOS path and filename | | | | (1002,1306) VGA device PCI IDs | | | | | | | | | | | | | | | | | | | | | | | | | | | +----------------------------------------------------------------------+ | +--------------------------------------------------------------------------+ | <Select> < Exit > < Help > | +--------------------------------------------------------------------------+ \end{verbatim} } Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the Option ROM from Vendor's website. \subsubsection{Payload} coreboot in itself is "only" minimal code for initializing a mainboard with peripherals. After the initialization, it jumps to a payload. Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS is setting it in menuconfig. { \small \begin{verbatim} +------------------------------- Payload ---------------------------------+ | Arrow keys navigate the menu. <Enter> selects submenus --->. | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | | +----------------------------------------------------------------------+ | | | Add a payload (SeaBIOS) ---> | | | | SeaBIOS version (1.7.2.1) ---> | | | | [*] Use LZMA compression for payloads (NEW) | | | | | | | | | | | | | | | | | | | | | | | | | | | +----------------------------------------------------------------------+ | +--------------------------------------------------------------------------+ | <Select> < Exit > < Help > | +--------------------------------------------------------------------------+ \end{verbatim} The script in Makefile will automatically checkout, config, build the SeaBIOS source, and integrat the binary into the final image. % % Working with Git % \section{Working with Git} \subsection{Configuration of Git} Inside the checkout you should install a commit-msg hook that adds a Change-Id into commit messages, which uniquely identifies the logical change in Gerrit even across multiple iterations of the commit. The hook only needs to be installed once per clone, and installation can be done with: { \small \begin{verbatim} $ cd coreboot $ cp ./util/gitconfig/* .git/hooks \end{verbatim} } configure your name and email in git. { \small \begin{verbatim} $ git config --global user.name "Your Name Comes Here" $ git config --global user.email your.email@example.com' \end{verbatim} } The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit. Otherwise you can not push you code to community. Then run the following command once, to tell git that by default you want to submit all commits in the currently checked-out branch for review on gerrit: { \small \begin{verbatim} $ git config remote.origin.push HEAD:refs/for/master \end{verbatim} } The above configurations for git has been integrated into Makefile. You can run { \small \begin{verbatim} $ make gitconfig \end{verbatim} } \subsection{Work flow} It is recommended that you make a new branch when you start to work, not pushing changes to master. { \small \begin{verbatim} $ git checkout master -b mybranch \end{verbatim} } After you have done your changes, run: { \small \begin{verbatim} $ git add file_need_to_submit.c $ git commit -m "my first change." \end{verbatim} } % Does anyone have a better word to describe the phylosophy of spliting changes to patches? You need to realize that the changes you have made should be well devided into several commits. Each of them has one and only one meaning. You could use git rebase -i to split, squash, remove, rewrite you comment. Here is an example of a well-formatted commit message: { \small \begin{verbatim} examplecomponent: Refactor duplicated setup into a function Setting up the demo device correctly requires the exact same register values to be written into each of the PCI device functions. Moving the writes into a function allows also otherexamplecomponent to use them. Signed-off-by: Joe Hacker <joe@hacker.email> \end{verbatim} } Then you can push the code. { \small \begin{verbatim} $ git push \end{verbatim} } You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed. Often it might happen that the patch you sent for approval is not good enough from the first attempt. Gerrit and git make it easy to track patch evolution during the review process until patches meet our quality standards and are ready for approval. You can easily modify a patch sent to gerrit by you or even by someone else. Just apply it locally using one of the possible ways to do it, make a new local commit that fixes the issues reported by the reviewers, then rebase the change by preserving the same Change-ID. We recommend you to use the git rebase command in interactive mode, Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master. % % Working with Gerrit % \section{Working with Gerrit} \label{sec:gerrit} If you are a coreboot user, not planning to contribute, you can skip this section. \subsection{Get gerrit account} You need to get an OpenID first. Currently Google account give you an OpenID. It means, if you have a gmail account, you have an OpenID. You can try to signed in. click \url{http://review.coreboot.org} %\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png} { \small \begin{verbatim} +-----------------------------------------------------------+ |All Projects Documentation Register Sign In | |Open Merged Abandoned | |Search for status:open | +-----------------------------------------------------------+ |Subject Status Owner Project Branch Updated CR V | |cpu: Rename.. Alexandru coreboot master 1:20 PM +1 | |cpu: Only a.. Alexandru coreboot master 1:17 PM X | |arch/x86: D.. Alexandru coreboot master 1:09 PM | | | | Next -> | |Press '?' to view keyboard shortcuts | Powered by Gerrit | +-----------------------------------------------------------+ \end{verbatim} } Click ``Sign In'', You will get %\includegraphics[width=6.00in,height=4.00in]{openid.png} You will be redirected to Google to get logging in. % \includegraphics[width=6.00in,height=1.50in]{login.png} { \small \begin{verbatim} Sign In to Gerrit Code Review at review.coreboot.org +--------------------------------------------------+ +--------------------------------------------------+ [] Remember me Sign In Cancel Sign in with a Google Account Sign in with a Yahoo! ID What is OpenID? OpenID provides secure single-sign-on, without revealing your passwords to this website. There are many OpenID providers available. You may already be member of one! Get OpenID \end{verbatim} } \subsection{Configure account} Click the dropdown button near the user name and click ``Settings'' % \includegraphics[width=6.00in,height=4.00in]{settings} % \epsfig{figure=keystroke_left} % \epstopdf {file=settings.eps} % \epsfig{file=settings.eps} \label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once. { \small \begin{verbatim} Profile Username zbao Preferences Full Name Zheng Bao Watched Projects Email Address zheng.bao@amd.com Contact Information Registered Jun 28, 2011 4:33 PM SSH Public Keys Account ID 1000034 HTTP Password Identities Groups \end{verbatim} } \label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig { \small \begin{verbatim} Full Name __________________________________ Preferred Email ______________ Registered Email Save Changes \end{verbatim} } In ``SSH Public Keys'' section, upload your public key. { \small \begin{verbatim} Status Algorithm Key Comment Delete Add SSH Public Key > How to Generate an SSH Key +--------------------------+ | | | | | | | | | | | | | | | | | | +--------------------------+ clear Add Close \end{verbatim} } Click ``Add Key ...'' Go back to you linux command line and type: { \small \begin{verbatim} $ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/zhengbao/.ssh/id_rsa. Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub. The key fingerprint is: xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb@host.domain The key's randomart image is: +--[ RSA 2048]----+ | | | | | | | | | | | | | | | | | | +-----------------+ \end{verbatim} } The data in ~/.ssh/id\_rsa.pub is your public key. Copy them to the box in the page of ``SSH Public Keys'' and click add. In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout. { \small \begin{verbatim} Username XXX Password XXXXXXXXXXXX Generate Password Clear Password \end{verbatim} } \subsection{Reviewing Changes} For each listed changes in Gerrit, you can review, comment, evaluate, cherry-pick, and even re-submit them. For you own patches, only you can abandon them. Click in the file and commit message, you can add in-line comment. % % 14 Glossary % \section{Glossary} \begin{itemize} \item payload coreboot only cares about low level machine initialization, but also has very simple mechanisms to boot a file either from FLASHROM or IDE. That file, possibly a Linux Kernel, a boot loader or Etherboot, are called payload, since it is the first software executed that does not cope with pure initialization. \item flash device Flash devices are commonly used in all different computers since unlike ROMs they can be electronically erased and reprogrammed. \item Gerrit Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. Gerrit makes reviews easier by showing changes in a side-by-side display, and allowing inline comments to be added by any reviewer. Gerrit simplifies Git based project maintainership by permitting any authorized user to submit changes to the master Git repository, rather than requiring all approved changes to be merged in by hand by the project maintainer. This functionality enables a more centralized usage of Git. \end{itemize} \newpage % % 14 Bibliography % \section{Bibliography} \subsection{Additional Papers on coreboot} \begin{itemize} \item \textit{\url{http://www.coreboot.org/Documentation}} \end{itemize} \subsection {Links} \begin{itemize} \item Etherboot: \textit{\url{http://www.etherboot.org/}} \item OpenBIOS: \textit{\url{http://www.openbios.org/}} \item Flashrom: \textit{\url{http://www.flashrom.org/}} \item Seabios: \textit{\url{http://www.seabios.org/}} \end{itemize} \end{document}