summaryrefslogtreecommitdiff
path: root/Documentation/corebootBuildingGuide.tex
blob: 32918e8a82c7b708cfb68b24d58649c2694a0a12 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
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/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/main
\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 main.
{ \small
\begin{verbatim}
$ git checkout main -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 philosophy of splitting changes to patches?
You need to realize that the changes you have made should be well divided 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/main.

%
% 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 main   1:20 PM +1    |
|cpu: Only a..      Alexandru coreboot main   1:17 PM    X  |
|arch/x86: D..      Alexandru coreboot main   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 upstream 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}