diff options
Diffstat (limited to 'docs/git')
| -rw-r--r-- | docs/git/index.html | 622 |
1 files changed, 622 insertions, 0 deletions
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 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + + <style type="text/css"> + @import url('../css/main.css'); + </style> + + <title>Building libreboot from source</title> +</head> + +<body> + + <div class="section"> + <h1 id="pagetop">Building libreboot from source</h1> + <p> + This section relates to building libreboot from source, and + working with the git repository. + </p> + <p> + Or <a href="../index.html">Back to main index</a>. + </p> + <ul> + <li><a href="#build_dependencies">Install build dependencies</a></li> + <li><a href="#build_meta">Get the full source code from metadata (git clone)</a></li> + <li><a href="#build_bucts">How to build "bucts" (for LenovoBIOS X60/X60S/X60T/T60)</a></li> + <li><a href="#build_flashrom">How to build "flashrom"</a></li> + <li> + <a href="#config">Configuring libreboot</a> + <ul> + <li><a href="#config_dmidecode">dmidecode</a></li> + <li><a href="#config">Configuring libreboot</a></li> + <li><a href="#config_chromebook">Configuring libreboot for chromebooks</a></li> + </ul> + </li> + <li><a href="#build">How to build the ROM images</a></li> + </ul> + </div> + + <div class="section"> + + <h1 id="build_dependencies">Install build dependencies</h1> + + <p> + 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. + <b>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.</b> + </p> + + <div class="important"> + <p> + For Trisquel 7, you can run the following command:<br/> + $ <b>sudo ./build dependencies trisquel7</b> + </p> + <p> + For Parabola, you can run the following command:<br/> + $ <b>sudo ./build dependencies parabola</b><br/> + or:<br/> + # <b>./build dependencies parabola</b> + </p> + </div> + + <p> + For other GNU/Linux distributions, you can adapt the existing scripts. + </p> + + <p><a href="#pagetop">Back to top of page</a></p> + + </div> + + <div class="section"> + + <h1 id="build_meta">Get the full source code from metadata (git clone)</h1> + + <p> + 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). + </p> + + <p> + You can use the scripts included to download everything. + </p> + + <p> + First, <a href="#build_dependencies">install the build dependencies</a>. + </p> + + <p> + 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:<br/> + $ <b>git config --global user.name "Your Name"</b><br/> + $ <b>git config --global user.email your@emailaddress.com</b><br/> + This is what will also appear in git logs if you ever commit your own changes to a given repository. For + more information, see <a href="http://git-scm.com/doc">http://git-scm.com/doc</a>. + </p> + + <p> + Another nice config for you (optional, but recommended):<br/> + $ <b>git config --global core.editor nano</b><br/> + $ <b>git config --global color.status auto</b><br/> + $ <b>git config --global color.branch auto</b><br/> + $ <b>git config --global color.interactive auto</b><br/> + $ <b>git config --global color.diff auto</b> + </p> + + <p> + After that, run the script:<br/> + $ <b>./download all</b> + </p> + + <p> + 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. + </p> + + <p> + To build the ROM images, see <a href="#build">#build</a>. + </p> + + <p><a href="#pagetop">Back to top of page.</a></p> + + </div> + + <div class="section"> + + <h1 id="build_bucts">How to build "bucts" (for LenovoBIOS X60/X60S/X60T/T60)</h1> + + <p> + <b>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.</b> + </p> + + <p> + BUC.TS isn't really specific to these laptops, but is a bit inside the a register in the chipset on some Intel systems. + </p> + + <p> + 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 "<b>bucts 1</b>" 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 <a href="#build_flashrom">#build_flashrom</a>). + 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 "<b>bucts 0</b>" to + make the system boot from the normal (highest) block again. + </p> + + <p> + *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. + </p> + + <p> + 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). + </p> + + <p> + BUC.TS utility is included in libreboot_src.tar.xz and libreboot_util.tar.xz.<br/> + <b>If you downloaded from git, follow <a href="#build_meta">#build_meta</a> before you proceed.</b> + </p> + + <p> + "BUC" means "<b>B</b>ack<b>u</b>p <b>C</b>ontrol" (it's a register) and "TS" means "<b>T</b>op <b>S</b>wap" + (it's a status bit). Hence "bucts" (BUC.TS). TS 1 and TS 0 corresponds to bucts 1 and bucts 0. + </p> + + <p> + If you have the binary release archive, you'll find executables under ./bucts/. Otherwise if you need to build from source, continue reading. + </p> + + <p> + First, <a href="#build_dependencies">install the build dependencies</a>. + </p> + + <p> + To build bucts, do this in the main directory:<br/> + $ <b>./build module bucts</b> + </p> + + <p> + To statically compile it, do this:<br/> + $ <b>./build module bucts static</b> + </p> + + <p> + The "builddeps" script in libreboot_src also makes use of builddeps-bucts. + </p> + + <p><a href="#pagetop">Back to top of page.</a></p> + + </div> + + <div class="section"> + + <h1 id="build_flashrom">How to build "flashrom"</h1> + + <p> + Flashrom is the utility for flashing/dumping ROM images. This is what you will use to install libreboot. + </p> + + <p> + Flashrom source code is included in libreboot_src.tar.xz and libreboot_util.tar.xz.<br/> + <b>If you downloaded from git, follow <a href="#build_meta">#build_meta</a> before you proceed.</b> + </p> + + <p> + 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. + </p> + + <p> + First, <a href="#build_dependencies">install the build dependencies</a>. + </p> + + <p> + To build it, do the following in the main directory:<br/> + $ <b>./build module flashrom</b> + </p> + + <p> + To statically compile it, do the following in the main directory:<br/> + $ <b>./build module flashrom static</b> + </p> + + <p> + After you've done that, under ./flashrom/ you will find the following executables: + </p> + <ul> + <li> + <b>flashrom</b> + <ul> + <li>For flashing while coreboot or libreboot is running.</li> + </ul> + </li> + <li> + <b>flashrom_lenovobios_sst</b> + <ul> + <li>This is patched for flashing while Lenovo BIOS is running on an X60 or T60 with the SST25VF016B (SST) flash chip.</li> + </ul> + </li> + <li> + <b>flashrom_lenovobios_macronix</b> + <ul> + <li>This is patched for flashing while Lenovo BIOS is running on an X60 or T60 with the MX25L1605D (Macronix) flash chip.</li> + </ul> + </li> + </ul> + + <p> + The "builddeps" script in libreboot_src also makes use of builddeps-flashrom. + </p> + + <p><a href="#pagetop">Back to top of page.</a></p> + + </div> + + <div class="section"> + + <h1 id="config">Configuring libreboot</h1> + + <p> + 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 <a href="../maintain/index.html#newboard_libreboot">../maintain/index.html#newboard_libreboot</a>. + </p> + + <p> + If you've already built a kernel before, you know how to use this interface. + </p> + + <div class="subsection"> + <h2 id="config_dmidecode"> + dmidecode + </h2> + <p> + There is certain information that can be useful to enter in particular: + </p> + <ul> + <li>Local version string</li> + <li>SMBIOS Serial Number</li> + <li>SMBIOS Manufacturer</li> + <li>SMBIOS Version</li> + <li>SMBIOS Product name</li> + </ul> + <p> + This information can be obtained using:<br/> + <b>$ sudo dmidecode</b><br/> + <b># dmidecode</b> + </p> + <p> + Specifically, it's good practise to enter the same information for libreboot that you found when running this + with the original BIOS or firmware. <b>libreboot has already done this for you. This information is for reference, + in the hope that it will be useful.</b> + </p> + <p> + 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). + </p> + </div> + + <h2 id="config">GRUB payload</h2> + + <p> + GRUB is one of the payloads that libreboot targets. + </p> + + <p> + Configurations are then saved as files called <b>".config"</b>. Copies of each configuration used + for each system type by the libreboot build scripts are stored in resources/libreboot/config/grub/ + </p> + + <div class="subsection"> + <h3 id="config_x86"> + Generic configuration file (file: resources/libreboot/config/payload/board/config) + </h3> + <ul> + <li>General setup / Expert mode = <i>enable</i></li> + <li>General / Use CMOS for configuration values = <i>enable</i></li> + <li>Mainboard / Mainboard vendor = <i>Name of manufacturer</i></li> + <li>Mainboard / Mainboard model = <i>Model name</i></li> + <li>Mainboard / ROM chip size = <i>size of flash chip</i></li> + <li>Chipset / Include CPU microcode in CBFS = <i>Do not include microcode updates</i></li> + <li>Devices / Use native graphics initialization = <i>enable</i></li> + <li> + Display / Keep VESA framebuffer = <i>disable</i> (disable for text-mode graphics, enable for coreboot vesa framebuffer) + <ul> + <li>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.</li> + </ul> + </li> + <li>Generic Drivers / USB 2.0 EHCI debug dongle support = <i>Enable</i></li> + <li>Generic Drivers / Enable early (pre-RAM) usbdebug = <i>Enable</i></li> + <li>Generic Drivers / Type of dongle = <i>Net20DC or compatible</i></li> + <li>Generic Drivers / Digitizer = <i>Present</i></li> + + <li>Console / USB dongle console output = <i>enable</i></li> + <li>Payload / Add a payload = <i>An ELF executable payload</i></li> + <li>Payload / Payload path and filename = <i>grub.elf</i></li> + </ul> + <p> + Now go back into Devices: + </p> + <ul> + <li>Devices / Run VGA Option ROMs = <i>disable</i></li> + <li>Devices / Run Option ROMs on PCI devices = <i>disable</i></li> + </ul> + <p> + The resulting .config file was saved as resources/libreboot/config/<b>payload/board/config</b> and is used by the build + scripts for this system. + </p> + </div> + + <h2 id="config_chromebook">Configuring libreboot for chromebooks</h2> + <p> + Depthcharge is one of the payloads that libreboot targets. + </p> + <p> + Configurations are then saved as files called <b>".config"</b>. Copies of each configuration used + for each system type by the libreboot build scripts are stored in resources/libreboot/config/depthcharge/ + </p> + <div class="subsection"> + <h3 id="config_arm"> + Generic configuration file (file: resources/libreboot/config/depthcharge/board/config) + </h3> + <ul> + <li>Mainboard / Mainboard vendor = <i>Google</i></li> + <li>Mainboard / Mainboard model = <i>name of model</i></li> + <li>Chipset / ChromeOS / Build for ChromeOS = <i>enable</i></li> + <li>Chipset / ChromeOS / Verify firmware with vboot. = <i>disable</i></li> + <li>Payload / Add a payload = <i>An ELF executable payload</i></li> + <li>Payload / Payload path and filename = <i>depthcharge.elf</i></li> + </ul> + <p> + The resulting .config file was saved as resources/libreboot/config/<b>depthcharge/board/config</b> and is used by the build + scripts for this system. + </p> + </div> + <p><a href="#pagetop">Back to top of page.</a></p> + + </div> + + <div class="section"> + + <h1 id="build">How to build the ROM images</h1> + + <p>You don't need to do much, as there are scripts already written for you that can build everything automatically.</p> + + <p> + 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. + </p> + + <p> + First, <a href="#build_dependencies">install the build dependencies</a>. + </p> + <p> + If you downloaded libreboot from git, refer to <a href="#build_meta">#build_meta</a>. + </p> + + <p> + Build all of the components used in libreboot:<br/> + $ <b>./build module all</b> + </p> + + <p> + You can also build each modules separately, using <i>./build module modulename</i>. + To see the possible values for <i>modulename</i>, use:<br/> + $ <b>./build module list</b> + </p> + + <p> + After that, build the ROM images (for all boards):<br/> + $ <b>./build roms withgrub</b><br/> + Alternatively, you can build for a specific board or set of boards. + For example:<br/> + $ <b>./build roms withgrub x60</b><br/> + $ <b>./build roms withgrub x200_8mb</b><br/> + $ <b>./build roms withgrub x60 x200_8mb</b><br/> + The list of board options can be found by looking at the directory + names in <b>resources/libreboot/config/grub/</b>. + </p> + <p> + For those boards which use the depcharge payload, you must use: + $ <b>./build roms withdepthcharge</b><br/> + You can also build for a specific board or set of boards. For example:<br/> + $ <b>./build roms withdepthcharge veyron_speedy</b> + </p> + + <p> + To clean (reverse) everything, do the following:<br/> + $ <b>./build clean all</b> + </p> + + <p> + The ROM images will be stored under <b>bin/<i>payload</i>/</b>, + where <i>payload</i> could be <i>grub</i>, <i>depthcharge</i>, <i>seabios</i>, or + whatever other payload those images were built for. + </p> + + <div class="subsection"> + + <h2>Preparing release archives (optional)</h2> + + <p> + <b>This is only confirmed to work (tested) in Trisquel 7. Parabola *fails* at this stage + (for now). For all other distros, YMMV.</b> + </p> + + <p> + This is mainly intended for use with the git repository. + These commands will work in the release archive (_src), unless otherwise noted below. + </p> + + <p> + The archives will appear under <i>release/${version}/</i>; + ${version} will either be set using <i>git describe</i> or, + if a <i>version</i> file already exists (_src release archive), + then it will simply re-use that. + </p> + + <p> + Tag the current commit, and that version will appear in both the ${version} + string on the directory under <i>release/</i>, and in the file names of the + archives. Otherwise, whatever git uses for <i>git describe --tags HEAD</i> + will be used. + </p> + + <p> + Utilities (static executables):<br/> + $ <b>./build release util</b> + </p> + <p> + Archive containing flashrom and bucts source code:<br/> + $ <b>./build release tobuild</b> + </p> + <p> + Documentation archive (<b>does not work on _src release archive, only git</b>):<br/> + $ <b>./build release docs</b> + </p> + <p> + ROM image archives:<br/> + $ <b>./build release roms</b> + </p> + <p> + Source code archive:<br/> + $ <b>./build release src</b> + </p> + <p> + SHA512 sums of all other release archives that have been generated:<br/> + $ <b>./build release sha512sums</b> + </p> + + <p> + 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: <b>nvramtool, cbfstool, ich9deblob, cbmem</b>. + </p> + + <p> + If you are building on an x86_64 host, this will build statically linked 32- *and* 64-bit binaries for + <b>cbmem</b>, <b>ich9deblob</b>, <b>cbfstool</b> and <b>nvramtool</b>. + </p> + <p> + <b>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.</b> + </p> + <p> + The same applies if you want to include statically linked flashrom binaries for ARM. + </p> + + <p> + armv7l binaries (tested on a BeagleBone Black) are also included in libreboot_util, for: + </p> + <ul> + <li>cbfstool</li> + <li>ich9gen</li> + <li>ich9deblob</li> + <li>flashrom</li> + </ul> + + <p> + If you are building binaries on a live system or chroot (for flashrom/bucts), you can use the following to statically link them:<br/> + $ <b>./build module flashrom static</b><br/> + $ <b>./build module bucts static</b> + </p> + + <p> + 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). + </p> + + <p> + The command that you used for generating the release archives will also run the following command:<br/> + $ <b>./build release tobuild</b><br/> + The archive <b>tobuild.tar.xz</b> will have been created under <b>release/</b>, containing bucts, flashrom and all other required + resources for building them. + </p> + + <p> + You'll find that the files libreboot_util.tar.xz and libreboot_src.tar.xz have been created, under <b>release/</b>. + </p> + + <p> + The ROM images will be stored in separate archives for each system, under <b>release/rom/</b>. + </p> + + </div> + + <p><a href="#pagetop">Back to top of page</a></p> + + </div> + + <div class="section"> + + <p> + Copyright © 2014, 2015, 2016 Leah Rowe <info@minifree.org><br/> + 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 <a href="../gfdl-1.3.txt">../gfdl-1.3.txt</a> + </p> + + <p> + Updated versions of the license (when available) can be found at + <a href="https://www.gnu.org/licenses/licenses.html">https://www.gnu.org/licenses/licenses.html</a> + </p> + + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + + </div> + +</body> +</html> |