From 4b18a922f0ab597fc010beeef01cee332fd48705 Mon Sep 17 00:00:00 2001 From: Martin Roth Date: Sat, 3 Jun 2017 20:16:01 -0600 Subject: 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 Reviewed-on: https://review.coreboot.org/20031 Tested-by: build bot (Jenkins) Reviewed-by: Arthur Heymans --- Documentation/AMD-S3.txt | 18 +- Documentation/CorebootBuildingGuide.tex | 671 -------------------------------- Documentation/Intel/SoC/soc.html | 2 +- Documentation/Makefile | 14 +- Documentation/acpi/gpio.md | 2 +- Documentation/cbfs.txt | 6 +- Documentation/corebootBuildingGuide.tex | 671 ++++++++++++++++++++++++++++++++ 7 files changed, 692 insertions(+), 692 deletions(-) delete mode 100644 Documentation/CorebootBuildingGuide.tex create mode 100644 Documentation/corebootBuildingGuide.tex (limited to 'Documentation') diff --git a/Documentation/AMD-S3.txt b/Documentation/AMD-S3.txt index 48d4c8f3e7..bfabcbe29d 100644 --- a/Documentation/AMD-S3.txt +++ b/Documentation/AMD-S3.txt @@ -13,7 +13,7 @@ /_/ \_\_| |_|_____/ |_____/ |____/ - S3 in Coreboot (V 1.2) + S3 in coreboot (V 1.2) ---------------------------------------- Zheng Bao @@ -78,7 +78,7 @@ as reserved in e820, or BIOS saves the content into reserved space. Here is the address Map for S3 Resume. Assumingly the total memory is 1GB. 00000000 --- 00100000 BIOS Reserved area. 00100000 --- 00200000 Free -00200000 --- 01000000 Coreboot ramstage area. +00200000 --- 01000000 coreboot ramstage area. 01000000 --- 2e160000 Free 2e160000 --- 2e170000 ACPI table 2e170000 --- 2ef70000 OSRAM @@ -99,7 +99,7 @@ board.[2] Provided by Southbridge vendor code. Early is called before PCI enumeration, and Late is called after that. -Lifecycle of booting, sleeping and waking Coreboot and Ubuntu +Lifecycle of booting, sleeping and waking coreboot and Ubuntu ============================================================= 1. Cold boot. For a system with S3 feature, the BIOS needs to save some data to @@ -130,7 +130,7 @@ when system wakeups. As we mentioned, Firmware detects the SLP_TYPx to find out if the board wakes up. In romstage.c, AmdInitReset and AmdInitEarly are called as they are during cold boot. AmdInitResume and AmdS3LateRestore are -called only during resume. For whole ramstage, Coreboot goes through +called only during resume. For whole ramstage, coreboot goes through almost the same way as cold boot, other than not calling the AmdInitMid, AmdInitLate and AmdS3Save, and restoring all the MTRRs. At last step of coreboot stage, coreboot finds out the wakeup vector in FADT, @@ -141,13 +141,13 @@ When Linux resumes, all the sleeping scripts call their resume hooks. If we are more lucky, all the scripts can go through. More chances that the 99video hangs or fails to get the display back. Sometimes it can fixed if CONFIG_S3_VGA_ROM_RUN is unset in -Coreboot/Kconfig. That needs more troubleshooting. +coreboot/Kconfig. That needs more troubleshooting. Reference ========= [1] ACPI40a, http://www.acpi.info/spec40a.htm -[2] Coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/ -[3] Coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c -[4] Coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c -[5] Coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c +[2] coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/ +[3] coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c +[4] coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c +[5] coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c diff --git a/Documentation/CorebootBuildingGuide.tex b/Documentation/CorebootBuildingGuide.tex deleted file mode 100644 index f18cc18719..0000000000 --- a/Documentation/CorebootBuildingGuide.tex +++ /dev/null @@ -1,671 +0,0 @@ -% -% This document is released under the GPL -% Initially written by Stefan Reinauer, -% - -\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://@review.coreboot.org:29418/coreboot -$ git clone https://[:@]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. selects submenus --->. | -| Highlighted letters are hotkeys. Pressing includes, excludes, | -| modularizes features. Press to exit, for Help, | -| for Search. Legend: [*] built-in [ ] excluded module < > | -| +---------------------------------------------------------------------+ | -| | General setup ---> | | -| | Mainboard ---> | | -| | Architecture (x86) ---> | | -| | Chipset ---> | | -| | Devices ---> | | -| | VGA BIOS ---> | | -| | Display ---> | | -| | PXE ROM ---> | | -| | Generic Drivers ---> | | -| | Console ---> | | -| | [ ] Relocatable Modules | | -| | System tables ---> | | -| | Payload ---> | | -| | Debugging ---> | | -| | --- | | -| +----v(+)-------------------------------------------------------------+ | -+-------------------------------------------------------------------------+ -| < 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. selects submenus --->. | -| Highlighted letters are hotkeys. Pressing includes, excludes, | -| modularizes features. Press to exit, for Help, | -| for Search. Legend: [*] built-in [ ] excluded module < > module | -| +----------------------------------------------------------------------+ | -| | Add a payload (SeaBIOS) ---> | | -| | SeaBIOS version (1.7.2.1) ---> | | -| | [*] Use LZMA compression for payloads (NEW) | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| +----------------------------------------------------------------------+ | -+--------------------------------------------------------------------------+ -| < 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. selects submenus --->. | +| Highlighted letters are hotkeys. Pressing includes, excludes, | +| modularizes features. Press to exit, for Help, | +| for Search. Legend: [*] built-in [ ] excluded module < > module | +| +----------------------------------------------------------------------+ | +| | [*] Add a VGA BIOS image | | +| | (vgabios.bin) VGA BIOS path and filename | | +| | (1002,1306) VGA device PCI IDs | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| +----------------------------------------------------------------------+ | ++--------------------------------------------------------------------------+ +| < 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 +\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} -- cgit v1.2.3