Documentation/CorebootBuildingGuide.tex

%
% 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}