From 8b2219bfa2da36e7809588ef723a10483a6e137f Mon Sep 17 00:00:00 2001 From: Francis Rowe Date: Wed, 05 Nov 2014 20:52:36 -0500 Subject: Documentation: *major* cleanup. Cleanup was long overdue. Old structure was messy and inefficient. --- (limited to 'docs/git') diff --git a/docs/git/index.html b/docs/git/index.html new file mode 100644 index 0000000..a2596c3 --- /dev/null +++ b/docs/git/index.html @@ -0,0 +1,503 @@ + + + + + + + + + Developing libreboot + + + + +

Developing libreboot

+

+ This section relates to building libreboot from source, and + working with the git repository. +

+

+ Or Back to main index. +

+ + +
+ +

Install build dependencies

+ +

+ Before doing anything, you need the dependencies first. +

+ + +

+ For all other GNU/Linux distributions, you may have to adapt these scripts. By all means send patches! +

+ +

Back to top of page

+ +
+ +

Get the full source code from metadata (git clone)

+ +

+ If you downloaded libreboot from git, then there are some steps to download and patch + the source code for all relevant dependencies. The archive in the git repository used to be + available as a tarball called 'libreboot_meta.tar.gz'. It contains 'metadata' (scripts) + which define how the source was created (where it came from). +

+ +

+ You can use the scripts included to download everything. +

+ +

+ First, install the build dependencies. +

+ +

+ After that, run the get script:
+ $ ./getall +

+ +

+ What this did was download everything (grub, coreboot, memtest86+, bucts, flashrom) + at the versions last tested for this release, and patch them. Read the script + in a text editor to learn more. +

+ +

+ To build the ROM's, see #build. +

+ +

Back to top of page.

+ +
+ +

How to build "bucts" (for LenovoBIOS X60/X60S/X60T/T60)

+ +

+ This is for Lenovo BIOS users on the ThinkPad X60/X60S, X60 Tablet and T60. If you have coreboot or libreboot running already, ignore this. +

+ +

+ Bucts is needed when flashing in software the X60/X60S/X60T/T60 ROM while Lenovo BIOS is running; + external flashing will be safe regardless. + Each ROM contains identical data inside the two final 64K region in the file. + This corresponds to the final two 64K regions in the flash chip. Lenovo BIOS will prevent you from writing the + final one, so running "bucts 1" will set the machine to boot from the other block instead (which + is writeable along with everything beneath it when using a patched flashrom. see #build_flashrom). + After shutting down and booting up after the first flash, + the final 64K block is writeable so you flash the ROM again with an unpatched flashrom and run "bucts 0" to + make the machine boot from the normal (highest) block again. +

+ +

+ BUC.TS utility is included in libreboot_src.tar.xz and libreboot_bin.tar.xz.
+ If you downloaded from git, follow #build_meta before you proceed. +

+ +

+ "BUC" means "Backup Control" (it's a register) and "TS" means "Top Swap" + (it's a status bit). Hence "bucts" (BUC.TS). TS 1 and TS 0 corresponds to bucts 1 and bucts 0. +

+ +

+ First, install the build dependencies. +

+ +

+ To build bucts, do this in the main directory:
+ $ ./builddeps-bucts +

+ +

+ The "builddeps" script in libreboot_src also makes use of builddeps-bucts. +

+ +

Back to top of page.

+ +
+ +

How to build "flashrom"

+ +

+ Flashrom is the utility for flashing/dumping ROM's. This is what you will use to install libreboot. +

+ +

+ Flashrom source code is included in libreboot_src.tar.gz and libreboot_bin.tar.gz.
+ If you downloaded from git, follow #build_meta before you proceed. +

+ +

+ First, install the build dependencies. +

+ +

+ To build it, do that in the main directory:
+ $ ./builddeps-flashrom +

+ +

+ After you've done that, under ./flashrom/ you will find the following executables: +

+ + +

+ The "builddeps" script in libreboot_src also makes use of builddeps-flashrom. +

+ +

Back to top of page.

+ +
+ +

Configuring libreboot

+ +

+ Before building a ROM in libreboot (or coreboot, for that matter), you need to configure it. + This is done using the following inside the source tree:
+ $ make menuconfig +

+ +

+ If you've already built a kernel before, you know how to use this interface. +

+ +

+ Configurations are then saved as files called ".config". Copies of each configuration used + for each machine type by the libreboot build scripts are stored in resources/libreboot/config/ +

+ +

+ dmidecode +

+

+ There is certain information that can be useful to enter in particular: +

+ +

+ This information can be obtained using:
+ $ sudo dmidecode
+ # dmidecode +

+

+ Specifically, it's good practise to enter the same information for libreboot that you found when running this + with the original BIOS or firmware. libreboot has already done this for you. This information is for reference, + in the hope that it will be useful. +

+ +

+ ThinkPad X60 configuration (file: resources/libreboot/config/x60/config) +

+ +

+ Now go back into Devices: +

+ +

+ The resulting .config file was saved as resources/libreboot/config/x60/config and is used by the build + scripts for this machine. +

+

+ This is based on an X60S with the Core 2 Duo L7400 processor. +

+

+ SMBIOS Version Number is ThinkPad X60 on the X60, but it is believed that the X60 and X60s both have identical + motherboards where the only difference is the CPU. This same configuration is used on the X60 and X60s. +

+ +

+ ThinkPad X60 Tablet configuration (file: resources/libreboot/config/x60t/config) +

+ +

+ Now go back into Devices: +

+ +

+ The resulting .config file was saved as resources/libreboot/config/x60t/config and is used by the build + scripts for this machine. +

+

+ This is based on an X60T with the Core 2 Duo L7400 processor. +

+ +

+ ThinkPad T60 configuration (file: resources/libreboot/config/t60/config) +

+ +

+ Go back into Devices: +

+ +

+ The resulting .config file was saved as resources/libreboot/config/t60/config and is used by the build + scripts for this machine. +

+

+ It is believed that the motherboards on 14.1" and 15.1" T60's are the same, so the same configuration is used + on both the 14.1" and 15.1" T60's. +

+ +

+ MacBook2,1 configuration (file: resources/libreboot/config/macbook21/config) +

+ +

+ Go back and disable option ROM's: +

+ +

+ The resulting .config file was saved as resources/libreboot/config/macbook21/config and is used by the build + scripts for this machine. This config is also used for the MacBook1,1. +

+ +

Back to top of page.

+ +
+ +

How to build the ROM's!

+ +

You don't need to do much, as there are scripts already written for you that can build everything automatically.

+ +

+ First, install the build dependencies. +

+

+ If you downloaded libreboot from git, refer to #build_meta. +

+ +

If running for the first time, run this:
+ $ ./buildall (also performs the "./build" step below)
+ Or if you only want to build dependencies (crossgcc, grub and so on):
+ $ ./builddeps

+ +

If you've already run ./builddeps and/or ./buildall before, you don't need to run them again. + Just run that from now on to build your ROM's:
+ $ ./build

+ +

To un-build (clean) the build dependencies that you built before, do the following:
+ This also deletes the ROM images under ./bin/:
+ $ ./cleandeps

+ +

Note: after running 'cleandeps', you will need to run 'builddeps' or 'buildall' again before you can use 'build'.

+ +

After 'build' or 'buildall' has finished, you'll find the ROM images for each machine under ./bin/

+ +

Preparing release archives (optional)

+ +

+ Run that script:
+ $ ./build-release +

+ +

+ You'll find that the files libreboot_bin.tar.xz and libreboot_src.tar.xz have been created. +

+ +

Back to top of page

+ +
+ +

How to add SeaBIOS to your ROM's

+ +

+ SeaBIOS isn't really needed since libreboot uses the GRUB payload which + is much better (for several reasons), so it is no longer included in the ROM + images by default. Instead, you can add it afterwards. +

+ +

+ In the supplied binary archives, or in your own (if you did 'build-release') you can add SeaBIOS + to the ROM images, along with SeaVGABIOS which is a free/libre Video BIOS implementation that wraps + around the 'native graphics initializitation' code in coreboot, for boards that have support for it. +

+ +

+ First, install the build dependencies. +

+ +

+ Build cbfstool:
+ $ ./builddeps-cbfstool +

+ +

+ Now:
+ $ ./addseabios +

+ +

+ SeaBIOS and SeaVGABIOS (which the build scripts created, and the build-release script put - compiled - + inside the binary archive) have now been added to all of the ROM images under ./bin/. A GRUB menuentry will show + up when you boot your machine, allowing you to use SeaBIOS. +

+ +

Back to top of page

+ +
+ +

+ Copyright © 2014 Francis Rowe <info@gluglug.org.uk>
+ This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. + A copy of the license can be found at ../license.txt. +

+ +

+ This document is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See ../license.txt for more information. +

+ + + -- cgit v0.9.1