sravan/system76-coreboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation: Update index.md and move files

Browse Source 
* Add more subdirectories and index.mds.
* Move "getting started" and "lessons" into sub-directories.
* Move "NativeRaminit" into northbridge/intel/sandybridge folder.
* Move "MultiProcessorInit" into soc/intel/icelake folder.
* Reference new files

Change-Id: I78c3ec0e8bcc342686277ae141a88d0486680978
Signed-off-by: Philipp Deppenwiese <zaolin@das-labor.org>
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/26262
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
This commit is contained in:
Philipp Deppenwiese
2018-05-13 15:47:18 +02:00
committed by Patrick Georgi
parent e462585c94
commit 438b463a8f
27 changed files with 73 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Documentation/lessons/index.md Normal file
View File

@@ -0,0 +1,4 @@
# Rookie Guide
* [Lesson 1: Starting from scratch](lesson1.md)
* [Lesson 2: Submitting a patch to coreboot.org](lesson2.md)

168
Documentation/lessons/lesson1.md Normal file
View File

@@ -0,0 +1,168 @@
coreboot lesson 1 - Starting from scratch
=========================================
From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for
a very basic build:
Download, configure, and build coreboot
---------------------------------------
### Step 1 - Install tools and libraries needed for coreboot
$ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev
### Step 2 - Download coreboot source tree
$ git clone https://review.coreboot.org/coreboot
$ cd coreboot
### Step 3 - Build the coreboot toolchain
Please note that this can take a significant amount of time
$ make crossgcc-i386 CPUS=$(nproc)
Also note that you can possibly use your system toolchain, but the results are
not reproducible, and may have issues, so this is not recommended. See step 5
to use your system toolchain.
### Step 4 - Build the payload - coreinfo
$ make -C payloads/coreinfo olddefconfig
$ make -C payloads/coreinfo
### Step 5 - Configure the build
* ##### Configure your mainboard
$ make menuconfig
select 'Mainboard' menu
Beside 'Mainboard vendor' should be '(Emulation)'
Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'
select < Exit >
These should be the default selections, so if anything else was set, run
`make distclean` to remove your old config file and start over.
* ##### Optionally use your system toolchain (Again, not recommended)
select 'General Setup' menu
select 'Allow building with any toolchain'
select < Exit >
* ##### Select the payload
select 'Payload' menu
select 'Add a Payload'
choose 'An Elf executable payload'
select 'Payload path and filename'
enter 'payloads/coreinfo/build/coreinfo.elf'
select < Exit >
select < Exit >
select < Yes >
##### check your configuration (optional step):
$ make savedefconfig
$ cat defconfig
There should only be two lines (or 3 if you're using the system toolchain):
CONFIG_PAYLOAD_ELF=y
CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"
### Step 6 - build coreboot
$ make
At the end of the build, you should see:
Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)
This means your build was successful. The output from the build is in the build
directory. build/coreboot.rom is the full rom file.
Test the image using QEMU
-------------------------
### Step 7 - Install QEMU
$ sudo apt-get install -y qemu
### Step 8 - Run QEMU
Start QEMU, and point it to the ROM you just built:
$ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
You should see the serial output of coreboot in the original console window, and
a new window will appear running the coreinfo payload.
Summary
-------
### Step 1 summary - Install tools and libraries needed for coreboot
You installed the minimum additional requirements for ubuntu to download and
build coreboot. Ubuntu already has most of the other tools that would be
required installed by default.
* `build-essential` is the basic tools for doing builds. It comes pre-installed
on some Ubuntu flavors, and not on others.
* `git` is needed to download coreboot from the coreboot git repository.
* `libncurses5-dev` is needed to build the menu for 'make menuconfig'
* `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot
toolchain.
If you started with a different distribution, you might need to install many
other items which vary by distribution.
### Step 2 summary - Download coreboot source tree
This will download a 'read-only' copy of the coreboot tree. This just means
that if you made changes to the coreboot tree, you couldn't immediately
contribute them back to the community. To pull a copy of coreboot that would
allow you to contribute back, you would first need to sign up for an account on
gerrit.
### Step 3 summary - Build the coreboot toolchain.
This builds one of the coreboot cross-compiler toolchains for X86 platforms.
Because of the variability of compilers and the other required tools between
the various operating systems that coreboot can be built on, coreboot supplies
and uses its own cross-compiler toolchain to build the binaries that end up as
part of the coreboot ROM. The toolchain provided by the operating system (the
'host toolchain') is used to build various tools that will run on the local
system during the build process.
### Step 4 summary - Build the payload
To actually do anything useful with coreboot, you need to build a payload to
include in the rom. The idea behind coreboot is that it does the minimum amount
possible before passing control of the machine to a payload. There are various
payloads such as grub or SeaBIOS that are typically used to boot the operating
system. Instead, we used coreinfo, a small demonstration payload that allows the
user to look at various things such as memory and the contents of coreboot's
cbfs - the pieces that make up the coreboot rom.
### Step 5 summary - Configure the build
This step configures coreboot's build options using the menuconfig interface to
Kconfig. Kconfig is the same configuration program used by the linux kernel. It
allows you to enable, disable, and change various values to control the coreboot
build process, including which mainboard(motherboard) to use, which toolchain to
use, and how the runtime debug console should be presented and saved.
Anytime you change mainboards in Kconfig, you should always run `make distclean`
before running `make menuconfig`. Due to the way that Kconfig works, values will
be kept from the previous mainboard if you skip the clean step. This leads to a
hybrid configuration which may or may not work as expected.
### Step 6 summary - Build coreboot
You may notice that a number of other pieces are downloaded at the beginning of
the build process. These are the git submodules used in various coreboot builds.
By default, the BLOBS submodule is not downloaded. This git submodule may be
required for other builds for microcode or other binaries. To enable downloading
this submodule, select the option "Allow use of binary-only repository" in the
"General Setup" menu of Kconfig
This attempts to build the coreboot rom. The rom file itself ends up in the
build directory as 'coreboot.rom'. At the end of the build process, the build
displayed the contents of the rom file.
### Step 7 summary - Install QEMU
QEMU is a processor emulator which we can use to show coreboot
### Step 8 summary - Run QEMU
Here's the command line broken down:
* `qemu-system-x86_64`
This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
ISA bridge.
* `-bios build/coreboot.rom`
Use the bios rom image that we just built. If this is left off, the standard
SeaBIOS image that comes with QEMU is used.
* `-serial stdio`
Send the serial output to the console. This allows you to view the coreboot
debug output.

281
Documentation/lessons/lesson2.md Normal file
View File

@@ -0,0 +1,281 @@
# coreboot Lesson 2: Submitting a patch to coreboot.org
## Part 1: Setting up an account at coreboot.org
If you already have an account, skip to Part 2.
Otherwise, go to <https://review.coreboot.org> in your preferred web browser.
Select **Register** in the upper right corner.
Select the appropriate sign-in. For example, if you have a Google account,
select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your
username for the account will be the username of the account you used to
sign-in with. (ex. your Google username).
## Part 2a: Set up RSA Private/Public Key
If you prefer to use an HTTP password instead, skip to Part 2b.
For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
<https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)>
and follow the instructions there. Then, skip to Part 3.
Additionally, that section of the Web site provides explanation on starting
an ssh-agent, which may be particularly helpful for those who anticipate
frequently uploading changes.
If you instead prefer to have review.coreboot.org specific instructions,
follow the steps below. Note that this particular section may have the
most up-to-date instructions.
If you do not have an RSA key set up on your account already (as is the case
with a newly created account), follow the instructions below; otherwise,
doing so could overwrite an existing key.
In the upper right corner, select your name and click on **Settings**.
Select **SSH Public Keys** on the left-hand side.
In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa".
Make a passphrase -- remember this phrase. It will be needed whenever you use
this RSA Public Key. **Note:** You might want to use a short password, or
forego the password altogether as you will be using it very often.
Open "id_rsa.pub", copy all contents and paste into the textbox under
"Add SSH Public Key" in the https://review.coreboot.org webpage.
## Part 2b: Setting up an HTTP Password
Alternatively, instead of using SSH keys, you can use an HTTP password. To do so,
after you select your name and click on **Settings** on the left-hand side, rather
than selecting **SSH Public Keys**, select **HTTP Password**.
Click **Generate Password**. This should fill the "Password" box with a password. Copy
the password, and add the following to your $HOME/.netrc file:
machine review.coreboot.org login YourUserNameHere password YourPasswordHere
where YourUserNameHere is your username, and YourPasswordHere is the password you
just generated.
## Part 3: Clone coreboot and configure it for submitting patches
Go to the **Projects** tab in the upper left corner and select **List**.
From the dropdown menu that appears, select "coreboot".
If you are using SSH keys, select **ssh** from the tabs under "Project coreboot"
and run the command that appears. This should prompt you for your id_rsa passphrase,
if you previously set one.
If you are using HTTP, instead, select **http** from the tabs under "Project coreboot"
and run the command that appears
After it finishes cloning, "cd coreboot" will take you into the local
git repository. Run "make gitconfig" to set up the hooks and configurations.
For example, you will be asked to run the following commands to set your
username and email.
git config --global user.name "Your Name"
git config --global user.email "Your Email"
## Part 4: Submit a commit
An easy first commit to make is fixing existing checkpatch errors and warnings
in the source files. To see errors that are already present, build the files in
the repository by running 'make lint' in the coreboot directory. Alternatively,
if you want to run 'make lint' on a specific directory, run:
for file in $(git ls-files | grep src/amd/quadcore); do \
util/lint/checkpatch.pl --file $file --terse; done
where <filepath> is the filepath of the directory (ex. src/cpu/amd/car).
Any changes made to files under the src directory are made locally,
and can be submitted for review.
Once you finish making your desired changes, use the command line to stage
and submit your changes. An alternative and potentially easier way to stage
and submit commits is to use git cola, a graphical user interface for git. For
instructions on how to do so, skip to Part 4b.
## Part 4a: Using the command line to stage and submit a commit
To use the command line to stage a commit, run
git add <filename>
where `filename` is the name of your file.
To commit the change, run
git commit -s
**Note:** The -s adds a signed-off-by line by the committer. Your commit should be
signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
what you set with git config earlier).
Running git commit first checks for any errors and warnings using lint. If
there are any, you must go back and fix them before submitting your commit.
You can do so by making the necessary changes, and then staging your commit again.
When there are no errors or warnings, your default text editor will open.
This is where you will write your commit message.
The first line of your commit message is your commit summary. This is a brief
one-line description of what you changed in the files using the template
below:
<filepath>: Short description
*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
**Note:** It is good practice to use present tense in your descriptions
and do not punctuate your summary.
Then hit Enter. The next paragraph should be a more in-depth explanation of the
changes you've made to the files. Again, it is good practice to use present
tense.
*ex. Fix space prohibited between function name and open parenthesis,
line over 80 characters, unnecessary braces for single statement blocks,
space required before open brace errors and warnings.*
When you have finished writing your commit message, save and exit the text
editor. You have finished committing your change. If, after submitting your
commit, you wish to make changes to it, running "git commit --amend" allows
you to take back your commit and amend it.
When you are done with your commit, run 'git push' to push your commit to
coreboot.org. **Note:** To submit as a draft, use
'git push origin HEAD:refs/drafts/master' Submitting as a draft means that
your commit will be on coreboot.org, but is only visible to those you add
as reviewers.
## Part 4b: Using git cola to stage and submit a commit
If git cola is not installed on your machine, see
https://git-cola.github.io/downloads.html for download instructions.
After making some edits to src files, rather than run "git add," run
'git cola' from the command line. You should see all of the files
edited under "Modified".
In the textbox labeled "Commit summary" provide a brief one-line
description of what you changed in the files according to the template
below:
<filepath>: Short description
*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
**Note:** It is good practice to use present tense in your descriptions
and do not punctuate your short description.
In the larger text box labeled 'Extended description...' provide a more
in-depth explanation of the changes you've made to the files. Again, it
is good practice to use present tense.
*ex. Fix space prohibited between function name and open parenthesis,
line over 80 characters, unnecessary braces for single statement blocks,
space required before open brace errors and warnings.*
Then press Enter two times to move the cursor to below your description.
To the left of the text boxes, there is an icon with an downward arrow.
Press the arrow and select "Sign Off." Make sure that you are signing off
with your name and email (i.e. **Your Name** **<Your Email>**, based on what
you set with git config earlier).
Now, review each of your changes and mark either individual changes or
an entire file as Ready to Commit by marking it as 'Staged'. To do
this, select one file from the 'Modified' list. If you only want to
submit particular changes from each file, then highlight the red and
green lines for your changes, right click and select 'Stage Selected
Lines'. Alternatively, if an entire file is ready to be committed, just
double click on the file under 'Modified' and it will be marked as
Staged.
Once the descriptions are done and all the edits you would like to
commit have been staged, press 'Commit' on the right of the text
boxes.
If the commit fails due to persisting errors, a text box will appear
showing the errors. You can correct these errors within 'git cola' by
right-clicking on the file in which the error occurred and selecting
'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and
'Stage' the corrected file again. It might be necessary to refresh
'git cola' in order for the file to be shown under 'Modified' again.
Note: Be sure to add any other changes that haven't already been
explained in the extended description.
When ready, select 'Commit' again. Once all errors have been satisfied
and the commit succeeds, move to the command line and run 'git push'.
**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master'
Submitting as a draft means that your commit will be on coreboot.org, but is
only visible to those you add as reviewers.
## Part 5: Getting your commit reviewed
Your commits can now be seen on review.coreboot.org if you select “My”
and click on “Changes” and can be reviewed by others. Your code will
first be reviewed by build bot (Jenkins), which will either give you a warning
or verify a successful build; if so, your commit will receive a +1. Other
users may also give your commit +1. For a commit to be merged, it needs
to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users
can give a +2.
## Part 6 (optional): bash-git-prompt
To help make it easier to understand the state of the git repository
without running 'git status' or 'git log', there is a way to make the
command line show the status of the repository at every point. This
is through bash-git-prompt.
Instructions for installing this are found at:
https://github.com/magicmonty/bash-git-prompt
**Note:** Feel free to search for different versions of git prompt,
as this one is specific to bash.
Alternatively, follow the instructions below:
Run the following two commands in the command line:
cd
git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1
**Note:** cd will change your directory to your home directory, so the
git clone command will be run there.
Finally, open the ~/.bashrc file and append the following two lines:
GIT_PROMPT_ONLY_IN_REPO=1
source ~/.bash-git-prompt/gitprompt.sh
Now, whenever you are in a git repository, it will continuously display
its state.
There also are additional configurations that you can change depending on your
preferences. If you wish to do so, look at the "All configs for .bashrc" section
on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
various lines that you can copy, uncomment and add to your .bashrc file to
change the configurations. Example configurations include avoid fetching remote
status, and supporting versions of Git older than 1.7.10.
## Appendix: Miscellaneous Advice
### Updating a commit after running git push:
Suppose you would like to update a commit that has already been pushed to the
remote repository. If the commit you wish to update is the most recent
commit you have made, after making your desired changes, stage the files
(either using git add or in git cola), and amend the commit. To do so,
if you are using the command line, run "git commit --amend." If you are
using git cola, click on the gear icon located on the upper left side under
**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage
the files you have changed, commit the changes, and run git push to push the
changes to the remote repository. Your change should be reflected in Gerrit as
a new patch set.
If, however, the commit you wish to update is not the most recent commit you
have made, you will first need to checkout that commit. To do so, find the
URL of the commit on <https://review.coreboot.org> and go to that page; if
the commit is one that you previously pushed, it can be found by selecting
**My** and then **Changes** in the upper left corner. To checkout this commit,
in the upper right corner, click on **Download**, and copy the command listed
next to checkout by clicking **Copy to clipboard**. Then, run the copied
command in your coreboot repository. Now, the last commit should be the most
recent commit to that patch; to update it, make your desired changes, stage
the files, then amend and push the commit using the instructions in the above
paragraph.