Documentation: change coreboot to lowercase

The word 'coreboot' should always be written in lowercase, even at the
start of a sentence.

Unfortunately, some external websites and projects are spelling coreboot
with an uppercase C, so references to those pages can't be changed
without breaking the link.

Change-Id: I79824da8a9ed36a1e4fe23a1711a89535267bf5f
Signed-off-by: Martin Roth <martinroth@google.com>
Reviewed-on: https://review.coreboot.org/20031
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>

1 files changed, 671 insertions, 0 deletions

diff --git a/Documentation/corebootBuildingGuide.tex b/Documentation/corebootBuildingGuide.tex
new file mode 100644
index 000000000000..867891b43182
--- /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}