Date: Mon, 22 Aug 2016 10:22:04 +0100 Subject: actually add the documentation directory. (I forgot git add in last commit) --- docs/git/index.html | 622 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 622 insertions(+) create mode 100644 docs/git/index.html (limited to 'docs/git') diff --git a/docs/git/index.html b/docs/git/index.html new file mode 100644 index 00000000..aaa2ff58 --- /dev/null +++ b/docs/git/index.html @@ -0,0 +1,622 @@ + + + + + + + + + Building libreboot from source + + + + +

Building libreboot from source

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

+ Or Back to main index. +

Install build dependencies
Get the full source code from metadata (git clone)
How to build "bucts" (for LenovoBIOS X60/X60S/X60T/T60)
How to build "flashrom"
+ Configuring libreboot +
+
How to build the ROM images

+ +

Install build dependencies

+ +

+ Before doing anything, you need the dependencies first. This is true if + you want to build libreboot from source, with either libreboot_src.tar.xz or git. + If you are using libreboot_util.tar.xz (binary archive) then you can ignore this, because + ROM images and statically compiled executables for the utilities are included. +

+ +

+ For Trisquel 7, you can run the following command:
+ $ sudo ./build dependencies trisquel7 +

+ For Parabola, you can run the following command:
+ $ sudo ./build dependencies parabola
+ or:
+ # ./build dependencies parabola +

+ +

+ For other GNU/Linux distributions, you can adapt the existing scripts. +

+ +

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. +

+ +

+ Since libreboot makes extensive use of git, you need to configure git properly. If you have not yet configured + git, then the minimum requirement is:
+ $ git config --global user.name "Your Name"
+ $ git config --global user.email your@emailaddress.com
+ This is what will also appear in git logs if you ever commit your own changes to a given repository. For + more information, see http://git-scm.com/doc. +

+ +

+ Another nice config for you (optional, but recommended):
+ $ git config --global core.editor nano
+ $ git config --global color.status auto
+ $ git config --global color.branch auto
+ $ git config --global color.interactive auto
+ $ git config --global color.diff auto +

+ +

+ After that, run the script:
+ $ ./download all +

+ +

+ 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 images, see #build. +

+ +

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. +

+ +

+ BUC.TS isn't really specific to these laptops, but is a bit inside the a register in the chipset on some Intel systems. +

+ +

+ 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 system 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 of libreboot, + the final 64K block is writeable so you flash the ROM again with an unpatched flashrom and run "bucts 0" to + make the system boot from the normal (highest) block again. +

+ +

+ *Libreboot ROM images have identical data in those two 64KiB regions because dd is used to do that, by the build system. + If you're building from upstream (coreboot), you have to do it manually. +

+ +

+ BUC.TS is backed up (powered) by the NVRAM battery (or CMOS battery, as some people call it). On thinkpads, + this is typically in a yellow plastic package with the battery inside, connected via power lines to the + mainboard. Removing that battery removes power to BUC.TS, resetting the bit back to 0 (if you previously set + it to 1). +

+ +

+ BUC.TS utility is included in libreboot_src.tar.xz and libreboot_util.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. +

+ +

+ If you have the binary release archive, you'll find executables under ./bucts/. Otherwise if you need to build from source, continue reading. +

+ +

+ First, install the build dependencies. +

+ +

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

+ +

+ To statically compile it, do this:
+ $ ./build module bucts static +

+ +

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

+ +

How to build "flashrom"

+ +

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

+ +

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

+ +

+ If you are using the binary release archive, then there are already binaries included + under ./flashrom/. The flashing scripts will try to choose the correct one for you. Otherwise + if you wish to re-build flashrom from source, continue reading. +

+ +

+ First, install the build dependencies. +

+ +

+ To build it, do the following in the main directory:
+ $ ./build module flashrom +

+ +

+ To statically compile it, do the following in the main directory:
+ $ ./build module flashrom static +

+ +

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

+ flashrom +
- For flashing while coreboot or libreboot is running.
+
+ flashrom_lenovobios_sst +
- This is patched for flashing while Lenovo BIOS is running on an X60 or T60 with the SST25VF016B (SST) flash chip.
+
+ flashrom_lenovobios_macronix +
- This is patched for flashing while Lenovo BIOS is running on an X60 or T60 with the MX25L1605D (Macronix) flash chip.
+

+ +

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

+ +

Configuring libreboot

+ +

+ Before building a ROM in libreboot (or coreboot, for that matter), you need to configure it. + Configuration files should already be included, so you don't need to do anything. This information + is only for reference. If you are updating or modifying coreboot-libre, and need to update the configs + in any way, refer to ../maintain/index.html#newboard_libreboot. +

+ +

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

+ +

+ dmidecode +

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

Local version string
SMBIOS Serial Number
SMBIOS Manufacturer
SMBIOS Version
SMBIOS Product name

+ 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. +

+ In practise, this information is useless and you can + just leave it on the defaults that coreboot uses (this + is what libreboot does, on most boards). +

+ +

GRUB payload

+ +

+ GRUB is one of the payloads that libreboot targets. +

+ +

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

+ +

+ Generic configuration file (file: resources/libreboot/config/payload/board/config) +

General setup / Expert mode = enable
General / Use CMOS for configuration values = enable
Mainboard / Mainboard vendor = Name of manufacturer
Mainboard / Mainboard model = Model name
Mainboard / ROM chip size = size of flash chip
Chipset / Include CPU microcode in CBFS = Do not include microcode updates
Devices / Use native graphics initialization = enable
+ Display / Keep VESA framebuffer = disable (disable for text-mode graphics, enable for coreboot vesa framebuffer) +
- Libreboot provides this with text-mode enabled by default, but it automatically patches a copy of the config at build time + to enable coreboot framebuffer for a separate set of ROM images, in each system.
+
Generic Drivers / USB 2.0 EHCI debug dongle support = Enable
Generic Drivers / Enable early (pre-RAM) usbdebug = Enable
Generic Drivers / Type of dongle = Net20DC or compatible
Generic Drivers / Digitizer = Present
Console / USB dongle console output = enable
Payload / Add a payload = An ELF executable payload
Payload / Payload path and filename = grub.elf

+ Now go back into Devices: +

Devices / Run VGA Option ROMs = disable
Devices / Run Option ROMs on PCI devices = disable

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

+ +

Configuring libreboot for chromebooks

+ Depthcharge is one of the payloads that libreboot targets. +

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

+ Generic configuration file (file: resources/libreboot/config/depthcharge/board/config) +

Mainboard / Mainboard vendor = Google
Mainboard / Mainboard model = name of model
Chipset / ChromeOS / Build for ChromeOS = enable
Chipset / ChromeOS / Verify firmware with vboot. = disable
Payload / Add a payload = An ELF executable payload
Payload / Payload path and filename = depthcharge.elf

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

+ +

How to build the ROM images

+ +

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

+ +

+ You can build libreboot from source on a 32-bit (i686) or 64-bit (x86_64) system. Recommended (if possible): x86_64. + ASUS KFSN4-DRE has 64-bit CPUs. + On a ThinkPad T60, you can replace the CPU (Core 2 Duo T5600, T7200 or T7600. T5600 recommended) for 64-bit support. + On an X60s, you can replace the board with one that has a Core 2 Duo L7400 (you could also use an X60 Tablet board with the same CPU). + On an X60, you can replace the board with one that has a Core 2 Duo T5600 or T7200 (T5600 is recommended). All MacBook2,1 laptops + are 64-bit, as are all ThinkPad X200, X200S, X200 Tablet, R400, T400 and T500 laptops. Warning: MacBook1,1 laptops are all 32-bit only. +

+ +

+ First, install the build dependencies. +

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

+ +

+ Build all of the components used in libreboot:
+ $ ./build module all +

+ +

+ You can also build each modules separately, using ./build module modulename. + To see the possible values for modulename, use:
+ $ ./build module list +

+ +

+ After that, build the ROM images (for all boards):
+ $ ./build roms withgrub
+ Alternatively, you can build for a specific board or set of boards. + For example:
+ $ ./build roms withgrub x60
+ $ ./build roms withgrub x200_8mb
+ $ ./build roms withgrub x60 x200_8mb
+ The list of board options can be found by looking at the directory + names in resources/libreboot/config/grub/. +

+ For those boards which use the depcharge payload, you must use: + $ ./build roms withdepthcharge
+ You can also build for a specific board or set of boards. For example:
+ $ ./build roms withdepthcharge veyron_speedy +

+ +

+ To clean (reverse) everything, do the following:
+ $ ./build clean all +

+ +

+ The ROM images will be stored under bin/payload/, + where payload could be grub, depthcharge, seabios, or + whatever other payload those images were built for. +

+ +

Preparing release archives (optional)

+ +

+ This is only confirmed to work (tested) in Trisquel 7. Parabola *fails* at this stage + (for now). For all other distros, YMMV. +

+ +

+ This is mainly intended for use with the git repository. + These commands will work in the release archive (_src), unless otherwise noted below. +

+ +

+ The archives will appear under release/${version}/; + ${version} will either be set using git describe or, + if a version file already exists (_src release archive), + then it will simply re-use that. +

+ +

+ Tag the current commit, and that version will appear in both the ${version} + string on the directory under release/, and in the file names of the + archives. Otherwise, whatever git uses for git describe --tags HEAD + will be used. +

+ +

+ Utilities (static executables):
+ $ ./build release util +

+ Archive containing flashrom and bucts source code:
+ $ ./build release tobuild +

+ Documentation archive (does not work on _src release archive, only git):
+ $ ./build release docs +

+ ROM image archives:
+ $ ./build release roms +

+ Source code archive:
+ $ ./build release src +

+ SHA512 sums of all other release archives that have been generated:
+ $ ./build release sha512sums +

+ +

+ If you are building on an i686 host, this will build statically linked 32-bit binaries in + the binary release archive that you created, + for: nvramtool, cbfstool, ich9deblob, cbmem. +

+ +

+ If you are building on an x86_64 host, this will build statically linked 32- *and* 64-bit binaries for + cbmem, ich9deblob, cbfstool and nvramtool. +

+ To include statically linked i686 and x86_64 binaries for bucts and flashrom, + you will need to build them on a chroot, a virtual system or a real + system where the host uses each given architecture. These packages are difficult + to cross-compile, and the libreboot project is still figuring out how to deal + with them. +

+ The same applies if you want to include statically linked flashrom binaries for ARM. +

+ +

+ armv7l binaries (tested on a BeagleBone Black) are also included in libreboot_util, for: +

cbfstool
ich9gen
ich9deblob
flashrom

+ +

+ If you are building binaries on a live system or chroot (for flashrom/bucts), you can use the following to statically link them:
+ $ ./build module flashrom static
+ $ ./build module bucts static +

+ +

+ The same conditions as above apply for ARM (except, building bucts on ARM is pointless, and for flashrom + you only need the normal executable since the lenovobios_sst and _macronix executables are meant + to run on an X60/T60 while lenovo bios is present, working around the security restrictions). +

+ +

+ The command that you used for generating the release archives will also run the following command:
+ $ ./build release tobuild
+ The archive tobuild.tar.xz will have been created under release/, containing bucts, flashrom and all other required + resources for building them. +

+ +

+ You'll find that the files libreboot_util.tar.xz and libreboot_src.tar.xz have been created, under release/. +

+ +

+ The ROM images will be stored in separate archives for each system, under release/rom/. +

+ +

+ Copyright © 2014, 2015, 2016 Leah Rowe <info@minifree.org>
+ Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license can be found at ../gfdl-1.3.txt +

+ +

+ Updated versions of the license (when available) can be found at + https://www.gnu.org/licenses/licenses.html +

+ +

+ UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. +

+ TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. +

+ The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. +

+ +

+ + + -- cgit v1.2.3-70-g09d2