Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1 | % |
| 2 | % This document is released under the GPL |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 3 | % Initially written by Stefan Reinauer, <stepan@coresystems.de> |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 4 | % |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 5 | |
| 6 | \documentclass[titlepage,12pt]{article} |
| 7 | \usepackage{a4} |
| 8 | \usepackage{graphicx} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 9 | \usepackage{epsfig} |
| 10 | \usepackage{epstopdf} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 11 | \usepackage{url} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 12 | \usepackage{color} |
| 13 | % \usepackage{geometry} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 14 | \usepackage[pdftex]{hyperref} |
| 15 | % \usepackage{makeidx} |
| 16 | % \makeindex |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 17 | % \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 18 | |
| 19 | \hypersetup{ |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 20 | urlbordercolor={1 1 1}, |
| 21 | menubordercolor={1 1 1}, |
| 22 | linkbordercolor={1 1 1}, |
| 23 | colorlinks=false, |
| 24 | % pdfpagemode=None, % PDF-Viewer starts without TOC |
| 25 | % pdfstartview=FitH, |
| 26 | pdftitle={Coreboot Porting Guide}, |
| 27 | pdfauthor={Zheng Bao}, |
| 28 | pdfsubject={coreboot configuration and build process}, |
| 29 | pdfkeywords={coreboot, AMD, configuration, Build} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 30 | } |
| 31 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 32 | \setlength{\parindent}{0pt} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 33 | \setlength{\hoffset}{0pt} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 34 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 35 | \title{Coreboot from Scratch} |
| 36 | \author{Stefan Reinauer $<$stepan@coresystems.de$>$\and Zheng Bao $<$zheng.bao@amd.com$>$} |
| 37 | \date{Dec 4th, 2013} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 38 | |
| 39 | \begin{document} |
| 40 | |
| 41 | \maketitle |
| 42 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 43 | \thispagestyle{empty} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 44 | |
| 45 | \tableofcontents |
| 46 | |
| 47 | \newpage |
| 48 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 49 | \section{What is Coreboot} |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 50 | coreboot aims to replace the normal BIOS found on x86, AMD64, PPC, |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 51 | Alpha, and other machines with a Linux kernel that can boot Linux from a cold |
| 52 | start. The startup code of an average coreboot port is about 500 lines of |
| 53 | assembly and 5000 lines of C. It executes 16 instructions to get into 32bit |
| 54 | protected mode and then performs DRAM and other hardware initializations |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 55 | required before Linux can take over. |
| 56 | |
| 57 | The projects primary motivation initially was maintenance of large |
| 58 | clusters. Not surprisingly interest and contributions have come from |
| 59 | people with varying backgrounds. Nowadays a large and growing number of |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 60 | Systems can be booted with coreboot, including embedded systems, |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 61 | Desktop PCs and Servers. |
| 62 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 63 | This document is used to build, modify, and port the CoreBoot code |
| 64 | base on the AMD platform. |
| 65 | |
| 66 | |
| 67 | \section{Changes} |
| 68 | |
| 69 | \begin{itemize} |
| 70 | \item 2013/12/20 Add Git, Gerrit, toolchains building. |
| 71 | \item 2009/04/19 replace LinuxBIOS with coreboot |
| 72 | \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ |
Elyes HAOUAS | e513878 | 2016-07-28 13:08:24 +0200 | [diff] [blame] | 73 | \item 2004/02/10 ACPI and option ROM updates |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 74 | \item 2003/11/18 initial release |
| 75 | \end{itemize} |
| 76 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 77 | % |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 78 | % Build Requirements |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 79 | % |
| 80 | |
| 81 | \section{Build Requirements} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 82 | To build coreboot for AMD64 from the sources you need a recent Linux. |
| 83 | SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD, |
| 84 | NetBSD are known to work fine. |
| 85 | |
| 86 | To build the toolchain, you need following host compilers: |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 87 | |
| 88 | \begin{itemize} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 89 | \item GNUtar |
| 90 | \item GNUpatch |
| 91 | \item GNUmake |
| 92 | \item GCC |
| 93 | \item binutils |
| 94 | \item bison |
| 95 | \item flex |
| 96 | \item m4 |
| 97 | \item wget |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 98 | \end{itemize} |
| 99 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 100 | Besides the tools above, after the toolchains are built, you also need the following |
| 101 | tools to build the source. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 102 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 103 | \begin{itemize} |
| 104 | \item git: Get the source code from repository |
| 105 | \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig |
| 106 | \item python: Optional for gdb. |
| 107 | \item perl: Optional for gdb. |
| 108 | \end{itemize} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 109 | |
| 110 | % |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 111 | % Getting Coreboot |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 112 | % |
| 113 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 114 | \section{Getting Coreboot} |
| 115 | The latest coreboot sources are available via GIT. |
| 116 | For users who doesn't need to change and commit the code: |
| 117 | { \small |
| 118 | \begin{verbatim} |
| 119 | $ git clone http://review.coreboot.org/p/coreboot |
| 120 | \end{verbatim} |
| 121 | } |
| 122 | For developers, you need to get a gerrit account which you can register |
| 123 | at \url{http://review.coreboot.org}. Please refer section ~\ref{sec:gerrit} |
| 124 | { \small |
| 125 | \begin{verbatim} |
| 126 | $ git clone ssh://<username>@review.coreboot.org:29418/coreboot |
| 127 | $ git clone http://[<username>:<password>@]review.coreboot.org/coreboot.git |
| 128 | \end{verbatim} |
| 129 | } |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 130 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 131 | Checks out a sub-repository in the 3rdparty directory. |
| 132 | { \small |
| 133 | \begin{verbatim} |
| 134 | $ git submodule update --init --checkout |
| 135 | \end{verbatim} |
| 136 | } |
| 137 | |
| 138 | % |
| 139 | % Building the toolchain |
| 140 | % |
| 141 | |
| 142 | \section{Building the toolchain} |
| 143 | Coreboot recommends and guarantees the toolchain integrated with Coreboot. |
| 144 | Linux distributions usually modify their compilers in ways incompatible with Coreboot. |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 145 | |
| 146 | { \small |
| 147 | \begin{verbatim} |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 148 | $ cd coreboot |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 149 | $ make crossgcc |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 150 | \end{verbatim} |
| 151 | } |
| 152 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 153 | or |
| 154 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 155 | { \small |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 156 | \begin{verbatim} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 157 | $ cd util/crossgcc |
| 158 | $ buildgcc |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 159 | \end{verbatim} |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 160 | } |
| 161 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 162 | The buildgcc will try to get packages from website. You need to make sure you can |
| 163 | get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs. |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 164 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 165 | { \small |
| 166 | \textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)} |
| 167 | |
| 168 | Target arch is now i386-elf |
| 169 | |
| 170 | Will skip GDB ... ok |
| 171 | |
| 172 | Downloading tar balls ... |
| 173 | |
| 174 | * gmp-5.1.2.tar.bz2 (cached) |
| 175 | |
| 176 | * mpfr-3.1.2.tar.bz2 (cached) |
| 177 | |
| 178 | * mpc-1.0.1.tar.gz (cached) |
| 179 | |
| 180 | * libelf-0.8.13.tar.gz (cached) |
| 181 | |
| 182 | * gcc-4.7.3.tar.bz2 (cached) |
| 183 | |
| 184 | * binutils-2.23.2.tar.bz2 (cached) |
| 185 | |
| 186 | * acpica-unix-20130626.tar.gz (cached) |
| 187 | |
| 188 | Downloaded tar balls ... \textcolor {green}{ok} |
| 189 | |
| 190 | Unpacking and patching ... |
| 191 | |
| 192 | * gmp-5.1.2.tar.bz2 |
| 193 | |
| 194 | * mpfr-3.1.2.tar.bz2 |
| 195 | |
| 196 | * mpc-1.0.1.tar.gz |
| 197 | |
| 198 | * libelf-0.8.13.tar.gz |
| 199 | |
| 200 | * gcc-4.7.3.tar.bz2 |
| 201 | |
| 202 | * binutils-2.23.2.tar.bz2 |
| 203 | |
| 204 | o binutils-2.23.2\_arv7a.patch |
| 205 | |
| 206 | o binutils-2.23.2\_no-bfd-doc.patch |
| 207 | |
| 208 | * acpica-unix-20130626.tar.gz |
| 209 | |
| 210 | Unpacked and patched ... \textcolor {green}{ok} |
| 211 | |
| 212 | Building GMP 5.1.2 ... \textcolor {green}{ok} |
| 213 | |
| 214 | Building MPFR 3.1.2 ... \textcolor {green}{ok} |
| 215 | |
| 216 | Building MPC 1.0.1 ... \textcolor {green}{ok} |
| 217 | |
| 218 | Building libelf 0.8.13 ... \textcolor {green}{ok} |
| 219 | |
| 220 | Building binutils 2.23.2 ... \textcolor {green}{ok} |
| 221 | |
| 222 | Building GCC 4.7.3 ... ok |
| 223 | |
| 224 | Skipping Expat (Python scripting not enabled) |
| 225 | |
| 226 | Skipping Python (Python scripting not enabled) |
| 227 | |
| 228 | Skipping GDB (GDB support not enabled) |
| 229 | |
| 230 | Building IASL 20130626 ... \textcolor {green}{ok} |
| 231 | |
| 232 | Cleaning up... \textcolor {green}{ok} |
| 233 | |
| 234 | \textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.} |
| 235 | } |
| 236 | If you are lucky, you can get toolchains located in util/crossgcc/xgcc. |
| 237 | |
| 238 | % |
| 239 | % Build Coreboot |
| 240 | % |
| 241 | |
| 242 | \section{Building Coreboot} |
| 243 | \subsection{Build main module of Coreboot} |
| 244 | { \small |
| 245 | \begin{verbatim} |
| 246 | $ cd coreboot |
| 247 | $ make menuconfig |
| 248 | .config - coreboot v4.0-4895-gc5025a4-dirty Configuration |
| 249 | +------------------------ coreboot Configuration -------------------------+ |
| 250 | | Arrow keys navigate the menu. <Enter> selects submenus --->. | |
| 251 | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | |
| 252 | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | |
| 253 | | for Search. Legend: [*] built-in [ ] excluded <M> module < > | |
| 254 | | +---------------------------------------------------------------------+ | |
| 255 | | | General setup ---> | | |
| 256 | | | Mainboard ---> | | |
| 257 | | | Architecture (x86) ---> | | |
| 258 | | | Chipset ---> | | |
| 259 | | | Devices ---> | | |
| 260 | | | VGA BIOS ---> | | |
| 261 | | | Display ---> | | |
| 262 | | | PXE ROM ---> | | |
| 263 | | | Generic Drivers ---> | | |
| 264 | | | Console ---> | | |
| 265 | | | [ ] Relocatable Modules | | |
| 266 | | | System tables ---> | | |
| 267 | | | Payload ---> | | |
| 268 | | | Debugging ---> | | |
| 269 | | | --- | | |
| 270 | | +----v(+)-------------------------------------------------------------+ | |
| 271 | +-------------------------------------------------------------------------+ |
| 272 | | <Select> < Exit > < Help > | |
| 273 | +------------------------------------------------------------------------- |
| 274 | \end{verbatim} |
| 275 | } |
| 276 | Select Mainboard -$>$ Mainboard Vendor -$>$ AMD |
| 277 | -$>$ Mainboard Model -$>$ Olive Hill |
| 278 | |
| 279 | Then save, exit and run make. |
| 280 | |
| 281 | { \small |
| 282 | \begin{verbatim} |
| 283 | $ make |
| 284 | \end{verbatim} |
| 285 | } |
| 286 | The built image, coreboot.rom, is located at folder build. |
| 287 | |
| 288 | \section{Programming coreboot to flash memory} |
| 289 | The image resulting from a coreboot build can be directly programmed to |
| 290 | a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the |
| 291 | Linux flash utility, flashrom. |
| 292 | |
| 293 | |
| 294 | \subsection{Add modules and payload} |
| 295 | |
| 296 | \subsubsection{VGA BIOS} |
| 297 | There is a big Chance that you need to get a VGA BIOS. |
| 298 | { \small |
| 299 | \begin{verbatim} |
| 300 | .config - coreboot v4.0 Configuration |
| 301 | ------------------------------------------------------------------------------ |
| 302 | +-------------------------------- VGA BIOS --------------------------------+ |
| 303 | | Arrow keys navigate the menu. <Enter> selects submenus --->. | |
| 304 | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | |
| 305 | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | |
| 306 | | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | |
| 307 | | +----------------------------------------------------------------------+ | |
| 308 | | | [*] Add a VGA BIOS image | | |
| 309 | | | (vgabios.bin) VGA BIOS path and filename | | |
| 310 | | | (1002,1306) VGA device PCI IDs | | |
| 311 | | | | | |
| 312 | | | | | |
| 313 | | | | | |
| 314 | | | | | |
| 315 | | | | | |
| 316 | | | | | |
| 317 | | +----------------------------------------------------------------------+ | |
| 318 | +--------------------------------------------------------------------------+ |
| 319 | | <Select> < Exit > < Help > | |
| 320 | +--------------------------------------------------------------------------+ |
| 321 | \end{verbatim} |
| 322 | } |
| 323 | Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the |
| 324 | Option ROM from Vendor's website. |
| 325 | |
| 326 | \subsubsection{Payload} |
| 327 | coreboot in itself is "only" minimal code for initializing a mainboard |
| 328 | with peripherals. After the initialization, it jumps to a payload. |
| 329 | |
| 330 | Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS |
| 331 | is setting it in menuconfig. |
| 332 | { \small |
| 333 | \begin{verbatim} |
| 334 | +------------------------------- Payload ---------------------------------+ |
| 335 | | Arrow keys navigate the menu. <Enter> selects submenus --->. | |
| 336 | | Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, | |
| 337 | | <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> | |
| 338 | | for Search. Legend: [*] built-in [ ] excluded <M> module < > module | |
| 339 | | +----------------------------------------------------------------------+ | |
| 340 | | | Add a payload (SeaBIOS) ---> | | |
| 341 | | | SeaBIOS version (1.7.2.1) ---> | | |
| 342 | | | [*] Use LZMA compression for payloads (NEW) | | |
| 343 | | | | | |
| 344 | | | | | |
| 345 | | | | | |
| 346 | | | | | |
| 347 | | | | | |
| 348 | | | | | |
| 349 | | +----------------------------------------------------------------------+ | |
| 350 | +--------------------------------------------------------------------------+ |
| 351 | | <Select> < Exit > < Help > | |
| 352 | +--------------------------------------------------------------------------+ |
| 353 | \end{verbatim} |
| 354 | The script in Makefile will automatically checkout, config, build the SeaBIOS source, |
| 355 | and integrat the binary into the final image. |
| 356 | |
| 357 | % |
| 358 | % Working with Git |
| 359 | % |
| 360 | |
| 361 | \section{Working with Git} |
| 362 | \subsection{Configuration of Git} |
| 363 | Inside the checkout you should install a commit-msg hook that adds a |
| 364 | Change-Id into commit messages, which uniquely identifies the logical |
| 365 | change in Gerrit even across multiple iterations of the commit. The |
| 366 | hook only needs to be installed once per clone, and installation can |
| 367 | be done with: |
| 368 | { \small |
| 369 | \begin{verbatim} |
| 370 | $ cd coreboot |
| 371 | $ cp ./util/gitconfig/* .git/hooks |
| 372 | \end{verbatim} |
| 373 | } |
| 374 | configure your name and email in git. |
| 375 | { \small |
| 376 | \begin{verbatim} |
| 377 | $ git config --global user.name "Your Name Comes Here" |
| 378 | $ git config --global user.email your.email@example.com' |
| 379 | \end{verbatim} |
| 380 | } |
| 381 | The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit. |
| 382 | Otherwise you can not push you code to community. |
| 383 | |
| 384 | Then run the following command once, to tell git that by default you |
| 385 | want to submit all commits in the currently checked-out branch for |
| 386 | review on gerrit: |
| 387 | { \small |
| 388 | \begin{verbatim} |
| 389 | $ git config remote.origin.push HEAD:refs/for/master |
| 390 | \end{verbatim} |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 391 | } |
| 392 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 393 | The above configurations for git has been integrated into Makefile. You can run |
| 394 | { \small |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 395 | \begin{verbatim} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 396 | $ make gitconfig |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 397 | \end{verbatim} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 398 | } |
| 399 | |
| 400 | \subsection{Work flow} |
| 401 | |
| 402 | It is recommended that you make a new branch when you start to work, not pushing changes to master. |
| 403 | { \small |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 404 | \begin{verbatim} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 405 | $ git checkout master -b mybranch |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 406 | \end{verbatim} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 407 | } |
| 408 | After you have done your changes, run: |
| 409 | { \small |
| 410 | \begin{verbatim} |
| 411 | $ git add file_need_to_submit.c |
| 412 | $ git commit -m "my first change." |
| 413 | \end{verbatim} |
| 414 | } |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 415 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 416 | % Does anyone have a better word to describe the phylosophy of spliting changes to patches? |
| 417 | You need to realize that the changes you have made should be well devided into |
| 418 | several commits. Each of them has one and only one meaning. You could use git rebase -i to |
| 419 | split, squash, remove, rewrite you comment. |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 420 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 421 | Here is an example of a well-formatted commit message: |
Ronald G. Minnich | 2c245ff | 2009-04-23 03:59:33 +0000 | [diff] [blame] | 422 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 423 | { \small |
| 424 | \begin{verbatim} |
| 425 | examplecomponent: Refactor duplicated setup into a function |
| 426 | |
| 427 | Setting up the demo device correctly requires the exact same register |
| 428 | values to be written into each of the PCI device functions. Moving the |
| 429 | writes into a function allows also otherexamplecomponent to use them. |
| 430 | |
| 431 | Signed-off-by: Joe Hacker <joe@hacker.email> |
| 432 | \end{verbatim} |
| 433 | } |
| 434 | |
| 435 | Then you can push the code. |
| 436 | { \small |
| 437 | \begin{verbatim} |
| 438 | $ git push |
| 439 | \end{verbatim} |
| 440 | } |
| 441 | |
| 442 | You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed. |
| 443 | |
| 444 | Often it might happen that the patch you sent for approval is not good |
| 445 | enough from the first attempt. Gerrit and git make it easy to track |
| 446 | patch evolution during the review process until patches meet our |
| 447 | quality standards and are ready for approval. |
| 448 | |
| 449 | You can easily modify a patch sent to gerrit by you or even by someone |
| 450 | else. Just apply it locally using one of the possible ways to do it, |
| 451 | make a new local commit that fixes the issues reported by the |
| 452 | reviewers, then rebase the change by preserving the same Change-ID. We |
| 453 | recommend you to use the git rebase command in interactive mode, |
| 454 | |
| 455 | Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master. |
| 456 | |
| 457 | % |
| 458 | % Working with Gerrit |
| 459 | % |
| 460 | |
| 461 | \section{Working with Gerrit} |
| 462 | \label{sec:gerrit} |
| 463 | If you are a coreboot user, not planning to contribute, you can skip this section. |
| 464 | \subsection{Get gerrit account} |
| 465 | 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. |
| 466 | click \url{http://review.coreboot.org} |
| 467 | |
| 468 | %\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png} |
| 469 | { \small |
| 470 | \begin{verbatim} |
| 471 | +-----------------------------------------------------------+ |
| 472 | |All Projects Documentation Register Sign In | |
| 473 | |Open Merged Abandoned | |
| 474 | |Search for status:open | |
| 475 | +-----------------------------------------------------------+ |
| 476 | |Subject Status Owner Project Branch Updated CR V | |
| 477 | |cpu: Rename.. Alexandru coreboot master 1:20 PM +1 | |
| 478 | |cpu: Only a.. Alexandru coreboot master 1:17 PM X | |
| 479 | |arch/x86: D.. Alexandru coreboot master 1:09 PM | |
| 480 | | | |
| 481 | | Next -> | |
| 482 | |Press '?' to view keyboard shortcuts | Powered by Gerrit | |
| 483 | +-----------------------------------------------------------+ |
| 484 | \end{verbatim} |
| 485 | } |
| 486 | Click ``Sign In'', You will get |
| 487 | |
| 488 | %\includegraphics[width=6.00in,height=4.00in]{openid.png} |
| 489 | |
| 490 | You will be redirected to Google to get logging in. |
| 491 | |
| 492 | % \includegraphics[width=6.00in,height=1.50in]{login.png} |
| 493 | { \small |
| 494 | \begin{verbatim} |
| 495 | Sign In to Gerrit Code Review at review.coreboot.org |
| 496 | +--------------------------------------------------+ |
| 497 | +--------------------------------------------------+ |
| 498 | [] Remember me |
| 499 | Sign In Cancel |
| 500 | Sign in with a Google Account |
| 501 | Sign in with a Yahoo! ID |
| 502 | What is OpenID? |
| 503 | |
| 504 | OpenID provides secure single-sign-on, without revealing your passwords to this website. |
| 505 | |
| 506 | There are many OpenID providers available. You may already be member of one! |
| 507 | |
| 508 | Get OpenID |
| 509 | \end{verbatim} |
| 510 | } |
| 511 | |
| 512 | \subsection{Configure account} |
| 513 | Click the dropdown button near the user name and click ``Settings'' |
| 514 | |
| 515 | % \includegraphics[width=6.00in,height=4.00in]{settings} |
| 516 | % \epsfig{figure=keystroke_left} |
| 517 | % \epstopdf {file=settings.eps} |
| 518 | % \epsfig{file=settings.eps} |
| 519 | |
| 520 | \label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once. |
| 521 | { \small |
| 522 | \begin{verbatim} |
| 523 | Profile Username zbao |
| 524 | Preferences Full Name Zheng Bao |
| 525 | Watched Projects Email Address zheng.bao@amd.com |
| 526 | Contact Information Registered Jun 28, 2011 4:33 PM |
| 527 | SSH Public Keys Account ID 1000034 |
| 528 | HTTP Password |
| 529 | Identities |
| 530 | Groups |
| 531 | \end{verbatim} |
| 532 | } |
| 533 | |
| 534 | \label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig |
| 535 | { \small |
| 536 | \begin{verbatim} |
| 537 | Full Name __________________________________ |
| 538 | Preferred Email ______________ Registered Email |
| 539 | |
| 540 | Save Changes |
| 541 | \end{verbatim} |
| 542 | } |
| 543 | |
| 544 | In ``SSH Public Keys'' section, upload your public key. |
| 545 | { \small |
| 546 | \begin{verbatim} |
| 547 | Status Algorithm Key Comment |
| 548 | |
| 549 | Delete |
| 550 | Add SSH Public Key |
| 551 | > How to Generate an SSH Key |
| 552 | +--------------------------+ |
| 553 | | | |
| 554 | | | |
| 555 | | | |
| 556 | | | |
| 557 | | | |
| 558 | | | |
| 559 | | | |
| 560 | | | |
| 561 | | | |
| 562 | +--------------------------+ |
| 563 | clear Add Close |
| 564 | \end{verbatim} |
| 565 | } |
| 566 | |
| 567 | Click ``Add Key ...'' |
| 568 | Go back to you linux command line and type: |
| 569 | { \small |
| 570 | \begin{verbatim} |
| 571 | $ ssh-keygen |
| 572 | Generating public/private rsa key pair. |
| 573 | Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa): |
| 574 | Enter passphrase (empty for no passphrase): |
| 575 | Enter same passphrase again: |
| 576 | Your identification has been saved in /home/zhengbao/.ssh/id_rsa. |
| 577 | Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub. |
| 578 | The key fingerprint is: |
| 579 | xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb@host.domain |
| 580 | The key's randomart image is: |
| 581 | +--[ RSA 2048]----+ |
| 582 | | | |
| 583 | | | |
| 584 | | | |
| 585 | | | |
| 586 | | | |
| 587 | | | |
| 588 | | | |
| 589 | | | |
| 590 | | | |
| 591 | +-----------------+ |
| 592 | \end{verbatim} |
| 593 | } |
| 594 | 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. |
| 595 | |
| 596 | In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout. |
| 597 | { \small |
| 598 | \begin{verbatim} |
| 599 | Username XXX |
| 600 | Password XXXXXXXXXXXX |
| 601 | |
| 602 | Generate Password Clear Password |
| 603 | |
| 604 | \end{verbatim} |
| 605 | } |
| 606 | |
| 607 | \subsection{Reviewing Changes} |
| 608 | For each listed changes in Gerrit, you can review, comment, evaluate, |
| 609 | cherry-pick, and even re-submit them. For you own patches, only you can |
| 610 | abandon them. Click in the file and commit message, you can add in-line comment. |
| 611 | |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 612 | % |
Ronald G. Minnich | ef5f8a7 | 2009-04-17 16:18:02 +0000 | [diff] [blame] | 613 | % 14 Glossary |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 614 | % |
| 615 | |
| 616 | \section{Glossary} |
| 617 | \begin{itemize} |
| 618 | \item payload |
| 619 | |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 620 | coreboot only cares about low level machine initialization, but also has |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 621 | very simple mechanisms to boot a file either from FLASHROM or IDE. That |
| 622 | file, possibly a Linux Kernel, a boot loader or Etherboot, are called |
| 623 | payload, since it is the first software executed that does not cope with |
| 624 | pure initialization. |
| 625 | |
| 626 | \item flash device |
| 627 | |
| 628 | Flash devices are commonly used in all different computers since unlike |
| 629 | ROMs they can be electronically erased and reprogrammed. |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 630 | |
| 631 | \item Gerrit |
| 632 | |
| 633 | Gerrit is a web based code review system, facilitating online code |
| 634 | reviews for projects using the Git version control system. |
| 635 | |
| 636 | Gerrit makes reviews easier by showing changes in a side-by-side |
| 637 | display, and allowing inline comments to be added by any reviewer. |
| 638 | |
| 639 | Gerrit simplifies Git based project maintainership by permitting any |
| 640 | authorized user to submit changes to the master Git repository, rather |
| 641 | than requiring all approved changes to be merged in by hand by the |
| 642 | project maintainer. This functionality enables a more centralized |
| 643 | usage of Git. |
| 644 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 645 | \end{itemize} |
| 646 | |
| 647 | \newpage |
| 648 | |
| 649 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 650 | % 14 Bibliography |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 651 | % |
| 652 | |
| 653 | \section{Bibliography} |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 654 | \subsection{Additional Papers on coreboot} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 655 | |
| 656 | \begin{itemize} |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 657 | \item |
Stefan Reinauer | ebf2589 | 2009-04-21 21:45:11 +0000 | [diff] [blame] | 658 | \textit{\url{http://www.coreboot.org/Documentation}} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 659 | \end{itemize} |
| 660 | |
| 661 | \subsection {Links} |
| 662 | |
| 663 | \begin{itemize} |
| 664 | \item Etherboot: \textit{\url{http://www.etherboot.org/}} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 665 | \item OpenBIOS: \textit{\url{http://www.openbios.org/}} |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 666 | \item Flashrom: \textit{\url{http://www.flashrom.org/}} |
| 667 | \item Seabios: \textit{\url{http://www.seabios.org/}} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 668 | \end{itemize} |
| 669 | |
Zheng Bao | dea0a7f | 2015-11-17 23:50:14 +0800 | [diff] [blame] | 670 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 671 | \end{document} |