summaryrefslogtreecommitdiff
path: root/Documentation/corebootBuildingGuide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/corebootBuildingGuide.tex')
-rw-r--r--Documentation/corebootBuildingGuide.tex671
1 files changed, 671 insertions, 0 deletions
diff --git a/Documentation/corebootBuildingGuide.tex b/Documentation/corebootBuildingGuide.tex
new file mode 100644
index 0000000000..867891b431
--- /dev/null
+++ b/Documentation/corebootBuildingGuide.tex
@@ -0,0 +1,671 @@
+%
+% 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 https://review.coreboot.org/p/coreboot
+\end{verbatim}
+}
+For developers, you need to get a gerrit account which you can register
+at \url{https://review.coreboot.org}. Please refer section ~\ref{sec:gerrit}
+{ \small
+\begin{verbatim}
+$ git clone ssh://<username>@review.coreboot.org:29418/coreboot
+$ git clone https://[<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{https://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{https://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}