diff options
Diffstat (limited to 'docs/maintain')
| -rw-r--r-- | docs/maintain/index.html | 656 |
1 files changed, 656 insertions, 0 deletions
diff --git a/docs/maintain/index.html b/docs/maintain/index.html new file mode 100644 index 00000000..81f7e56a --- /dev/null +++ b/docs/maintain/index.html @@ -0,0 +1,656 @@ +<!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>Maintaining libreboot</title> +</head> + +<body> + + <div class="section"> + + <h1 id="pagetop">Maintaining libreboot</h1> + + <p> + This section relates to maintaining libreboot. + </p> + <p> + Do not follow anything here to the letter; is it only a rough guide + representing how libreboot is maintained (for reference). + </p> + <p> + This section of the documentation applies mainly to the + development version of libreboot, which is hosted in a git + repository. It is not intended for the release versions of + libreboot. + </p> + + <ul> + <li><a href="#overview">Overview</a></li> + <li> + <a href="#updating_coreboot">Updating coreboot-libre</a> + <ul> + <li><a href="#newboard_libreboot">Adding a new board to libreboot</a></li> + <li><a href="#newpatch_libreboot">Add/remove/modify patches in coreboot-libre</a></li> + </ul> + </li> + <li> + <a href="#updating_grub">Updating GRUB</a> + <ul> + <li><a href="#altbuild_grub_payload">Change how the GRUB payload (grub.elf) is built (utility: grub-assemble)</a></li> + <li><a href="#newconfig_grub">Modify the configuration used in GRUB</a></li> + <li><a href="../grub/index.html">Other maintenance-related tasks in GRUB</a></li> + </ul> + </li> + <li> + <a href="#updating_depthcharge">Updating depthcharge</a> + </li> + <li> + <a href="#updating_flashrom">Updating flashrom</a> + </li> + <li> + <a href="#updating_bucts">Updating bucts</a> + </li> + <li> + <a href="#updating_memtest86plus">Updating MemTest86+</a> + </li> + </ul> + + <p> + Or <a href="../index.html">Back to main index</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="overview">Overview</h1> + + <p> + The way the libreboot project is run is very similar to how + a GNU/Linux distribution project is run (but for the boot + firmware, not your operating system). Thus, libreboot is + a <i>coreboot distribution</i>. + </p> + <p> + This page demonstrates on a high level how + libreboot is maintained, how the project is run, how everything + goes together, etc. For a more detailed guide, refer to each + subsection for the various components/modules used in libreboot. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_coreboot">Updating coreboot-libre</h1> + + <p> + NOTE: it helps to own all libreboot-compatible systems here, + or have reliable (and fast) access to a team of testers. + </p> + + <p> + Coreboot-libre is the name of the deblobbed coreboot sources + used in libreboot. It is also the name of the collection + of scripts used for deblobbing coreboot, on each new update. + </p> + + <p> + This section shows an example of how to update (re-base) to + the latest version of coreboot, how to update the deblobbing + scripts, and so on. <b>This does not teach you how to + change what custom patches are used, nor does it tell + you how to add new boards to libreboot. It assumes that you + simply want to re-base to the latest version (for instance, + there could be bug fixes that you want). For those things + not listed in this section, you can refer to other sections + on this page instead.</b> + </p> + + <p> + Open these files in your editor (you will most likely be editing them): + </p> + <ul> + <li>resources/scripts/helpers/download/coreboot</li> + <li>resources/scripts/helpers/build/module/coreboot</li> + <li>resources/utilities/coreboot-libre/deblob</li> + <li>resources/utilities/coreboot-libre/nonblobs</li> + <li>resources/utilities/coreboot-libre/nonblobs_notes</li> + <li>resources/scripts/helpers/build/roms/helper</li> + <li>resources/scripts/helpers/build/roms/withgrub</li> + </ul> + + <p> + If you already had a coreboot/ directory in your libreboot + tree, delete it:<br/> + $ <b>rm -Rf coreboot/</b> + </p> + + <p> + Firstly, download coreboot. Do <b>not</b> use <b>./download coreboot</b> + for this, just clone coreboot, as it does in that script, like so:<br/> + $ <b>git clone http://review.coreboot.org/coreboot</b> + </p> + + <p> + $ <b>cd coreboot/</b><br/> + Get the ID of the latest commit in this clone, by reading the commit ID using + e.g.:<br/> + $ <b>git log</b><br/> + In <i>resources/scripts/helpers/download/coreboot</i> you will + find a line that says <i><b>git reset --hard</b></i> and then + a commit ID next to it. Replace this with the commit ID of the latest + commit from the coreboot version that you just downloaded. + </p> + <p> + You must also checkout the <i>vboot</i> submodule:<br/> + $ <b>git submodule update --init --checkout -- 3rdparty/vboot/</b> + </p> + <p> + Delete the .git* resources. For example:<br/> + $ <b>rm -Rf .git* 3rdparty/*/.git*</b><br/> + ...this is to avoid the deblobbing script from picking up files + in there as blobs, which would be only false positives and + increase the amount of time taken. Now come out of coreboot:<br/> + $ <b>cd ../</b> + </p> + + <p> + Check all coreboot file names/paths in <i>deblob</i>; if any + of them no longer exist at that name/path in the coreboot tree that you downloaded, + delete the reference(s) in <i>deblob</i>. + </p> + + <p> + Check all coreboot file names/paths in <i>nonblobs</i>; if + any of them no longer exist at that name/path in the coreboot tree that you downloaded, + delete the reference in <i>nonblobs</i>. + </p> + + <p> + Now, back in the main root directory of libreboot (git repository), + run the deblob script. This is to prevent the <i>findblobs</i> + scripts from finding the blobs that are already deleted + when running the <i>deblob</i> script. Like so:<br/> + $ <b>./resources/utilities/coreboot-libre/deblob</b> + </p> + + <p> + Now search for new blobs:<br/> + $ <b>cd resources/utilities/coreboot-libre/</b><br/> + $ <b>./findblobs</b><br/> + WARNING: this will take a <b>*long*</b> time. Be patient! + What this will do is look through the coreboot source directory, + looking for blobs. It will not find the blobs that you deleted + before (because they no longer exist), and it will ignore any + files listed in <i>nonblobs</i>. + </p> + + <p> + Once the <i>findblobs</i> script has finished, check the file + <i>tocheck</i> (from the root, this will be <i>resources/utilities/coreboot-libre/tocheck</i>). + These are the files detected as blobs; some might be blobs, some not. + The <i>findblobs</i> script doesn't know how to determine between blobs + and non-blobs, it only knows patterns. Distinguishing between blobs and + non-blobs must be performed by you, the human being. + </p> + <ul> + <li> + Files in <i>tocheck</i> that you identify as blobs, + should be added appropriately to <i>resources/utilities/coreboot-libre/deblob</i> + </li> + <li> + Files in <i>tocheck</i> that you identify as non-blobs, + should be added appropriately to <i>resources/utilities/coreboot-libre/nonblobs</i> - + also, if you feel it necessary, add an explanation of it in + <i>resources/utilities/coreboot-libre/nonblobs_notes</i> + </li> + </ul> + + <p> + Now come back to the main libreboot root directory (root + of the git clone). If you are still in resources/utilities/coreboot-libre/ + for instance, you would do something like:<br/> + $ <b>cd ../../../</b> + </p> + + <p> + Now delete the coreboot directory:<br/> + $ <b>rm -Rf coreboot/</b> + </p> + + <p> + Download coreboot again, only this time, using the download + script. The download script also applies custom patches + to coreboot (see resources/scripts/helpers/download/coreboot); + if they do not apply anymore, you will have to re-base them + and then update <i>resources/scripts/helpers/download/coreboot</i> + accordingly. Anyway, download coreboot like so:<br/> + $ <b>./download coreboot</b> + </p> + + <p> + If the custom patches no longer apply, and you have to re-base + (or replace?) some patches, please do this in coreboot upstream, + not in libreboot. Then re-include new patches from upstream, + into libreboot. Here is coreboot's guide for contributing + patches:<br/> + <a href="http://www.coreboot.org/Git">http://www.coreboot.org/Git</a>. + </p> + + <p> + Update all configs:<br/> + $ <b>./build config grubupdate</b><br/> + $ <b>./build config dcupdate</b><br/> + This simply takes all of the coreboot <b>.config</b> files from + <i>resources/libreboot/config/</i> and does <b>make oldconfig</b> + on them. It usually works. If it doesn't, you'll need to recreate + those configs from scratch using <b>./build config grubreplace</b> + or <b>./build config dcreplace</b> (optionally + add a config name), or <b>./build config grubmodify</b> + or <b>./build config dcmodify</b> (ditto) + (see <a href="../git/index.html#config">../git/index.html#config</a>) + </p> + + <p> + Finally, build *all* ROM images using the instructions at + <a href="../git/index.html">../git/index.html</a>, to verify + that everything still builds. + </p> + + <p> + Once you've verified that building isn't broken, test *all* + boards (you don't need to test all ROM images, only one + vesafb and one txtmode image for each configuration). If you + do not have all systems supported in libreboot, then you will + need to get other testers for those boards. + </p> + + <p> + If you have established a build issue, or a board no longer + works (booting issues, bugs during/after boot, etc), you'll + need to fix it upstream: + <a href="http://www.coreboot.org/Git">http://www.coreboot.org/Git</a> + and then re-update coreboot (or apply patches from upstream). + </p> + + <p> + You should also test the resulting ROM images from building + with the new or modified coreboot revision. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="newboard_libreboot">Adding a new board to libreboot</h1> + + <p> + Make sure that the board is supported, and that the patches + are included (if there are custom patches that you need). + Add configs for it like so (for GRUB payload):<br/> + $ <b>./build config grubreplace <i>payload</i>/<i>boardname</i></b><br/> + Alternatively, for depthcharge payload:<br/> + $ <b>./build config dcreplace <i>payload</i>/<i>boardname</i></b> + </p> + + <p> + This can also be used for replacing an existing config. + </p> + + <p> + Configure the board. Make sure to add the steps to the config section + in <a href="../git/index.html">../git/index.html</a>. + </p> + + <p> + When you're done, the config will be stored in <i>resources/libreboot/config/</i>. + Now build-test it and then check that it actually works. + </p> + + <p> + The following scripts may also need to be modified before building: + <i>resources/scripts/helpers/build/roms/withgrub</i> and + <i>resources/scripts/helpers/build/roms/helper</i> + </p> + + <p> + The following can be used when updating coreboot-libre (GRUB payload):<br/> + $ <b>./build config grubupdate</b><br/> + You must also do this for boards that use the depthcharge payload:<br/> + $ <b>./build config dcupdate</b><br/> + (adding a board name on the end is optional, for either of these) + </p> + + <p> + The following can be used if you want to modify an existing + configuration (GRUB payload):<br/> + $ <b>./build config grubmodify</b><br/> + For those boards which use the depthcharge payload:<br/> + $ <b>./build config dcmodify</b><br/> + (adding a board name on the end is optional) + </p> + + <p> + Examples (GRUB payload):<br/> + $ <b>./build config grubmodify x60</b><br/> + $ <b>./build config grubreplace x60</b><br/> + $ <b>./build config grubupdate x60</b><br/> + $ <b>./build config grubmodify kfsn4-dre</b><br/> + $ <b>./build config grubreplace kfsn4-dre</b><br/> + $ <b>./build config grubupdate kfsn4-dre</b><br/> + </p> + <p> + Examples (depthcharge payload):<br/> + $ <b>./build config dcmodify veyron_speedy</b><br/> + $ <b>./build config dcreplace veyron_speedy</b><br/> + $ <b>./build config dcupdate veyron_speedy</b> + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="newpatch_libreboot">Add/remove/modify patches in coreboot-libre</h1> + + <p> + Under <b>resources/scripts/helpers/download/coreboot</b> you can find + the instructions used for patching coreboot. + </p> + + <p> + Modify the commit ID on the <i>git reset --hard</i> line accordingly, + and update the list of patches used accordingly. Do not cherry-pick + from review.coreboot.org directly; instead, include the diff in + resources/libreboot/patch/ and use <i>git am</i> + (you can get the diff by using git-format-patch). + </p> + + <p> + When you're done, simply download coreboot again:<br/> + $ <b>./download coreboot</b> + </p> + + <p> + Finally, re-build the parts from coreboot that are used + by the build system (also builds GCC):<br/> + $ <b>./build module coreboot</b> + </p> + + <p> + Before running the above command, you can save time + by copying out the crossgcc that you compiled before + (from coreboot/util/crossgcc/) and then putting it back. + After you've done that, run everything in + <i>resources/scripts/helpers/build/module/coreboot</i> + except for the part that builds GCC. + <b>Only do this if the version is correct.</b> + </p> + + <p> + You should also test the resulting ROM images from building + with the new or modified coreboot revision. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_grub">Updating GRUB</h1> + + <p> + $ <b>rm -Rf grub/</b><br/> + $ <b>git clone git://git.savannah.gnu.org/grub.git</b><br/> + $ <b>cd grub/</b><br/> + $ <b>git log</b> + </p> + + <p> + Open the file <i>resources/scripts/helpers/download/grub</i> and + replace the commit ID on the line that performs <i>git reset --hard</i> + with the commit ID of the GRUB revision that you just downloaded. + </p> + + <p> + $ <b>cd ../</b><br/> + $ <b>./download grub</b> + </p> + + <p> + If it fails because of merge conflicts, you'll need to re-base + or (as appropriate) remove the offending patch(es) in + <i>resources/scripts/helpers/download/grub</i>. + </p> + + <p> + Finally, verify that it will build:<br/> + $ <b>./build module grub</b> + </p> + + <p> + Since GRUB is the payload in libreboot, you should also + build the ROM images and test them, with this different + GRUB version that you have prepared. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="altbuild_grub_payload">Change how the GRUB payload (grub.elf) is built (utility: grub-assemble)</h1> + + <p> + Look in <i>resources/utilities/grub-assemble/</i>. + </p> + + <p> + <i>gen.sh</i> creates ELF executables of GRUB with different configurations: + text-mode or framebuffer mode in coreboot. Essentially, + the text-mode version has no background nor any custom fonts, + and contains MemTest86+. You probably don't need to modify these + files at all. + </p> + + <p> + <i>modules.conf</i> defines which modules will be included in the GRUB + ELF executable. + </p> + + <p> + Since GRUB is the payload in libreboot, you should also + build the ROM images and test them, with this different + GRUB version that you have prepared. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="newconfig_grub">Modify the configuration used in GRUB</h1> + + <p> + Look in <i>resources/scripts/helpers/build/roms/withgrub</i> to + see how the GRUB configuration files are generated. + </p> + + <p> + You might need to modify this. You can also modify the + default configuration by making changes to the files + under <i>resources/grub/config/</i> + </p> + + <p> + Since GRUB is the payload in libreboot, you should also + build the ROM images and test them, with this different + GRUB version that you have prepared. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_depthcharge">Updating depthcharge</h1> + + <p> + The script to download depthcharge is: <i>resources/scripts/helpers/download/depthcharge</i>. + </p> + + <p> + Patches are in <i>resources/depthcharge/patch/</i>. + </p> + + <p> + The configuration used for depthcharge is located in <i>depthcharge/board</i>. + Each board has a <i>defconfig</i> Kconfig configuration and a </i>fmap.dts</i> FMAP device-tree configuration. + Those shouldn't need much attention, but when needed, it's best to modify them in the depthcharge tree (with patches) to keep things in one place. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_flashrom">Updating flashrom</h1> + + <p> + Modify these files: <i>resources/scripts/helpers/download/flashrom</i> + and <i>resources/scripts/helpers/build/module/flashrom</i>. + </p> + + <p> + Patches are in <i>resources/flashrom/patch/</i> + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_bucts">Updating bucts</h1> + + <p> + bucts doesn't really need updating, but the patches are + in <i>resources/bucts/patch</i>, the download script + is <i>resources/scripts/helpers/download/bucts</i> and + the build script is <i>resources/scripts/helpers/build/module/bucts</i>. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <h1 id="updating_memtest86plus">Updating MemTest86+</h1> + + <p> + MemTest86+ doesn't really need updating, but the patches are + in <i>resources/memtest86plus/patch</i>, the download script + is <i>resources/scripts/helpers/download/memtest86plus</i> and + the build script is <i>resources/scripts/helpers/build/module/memtest86plus</i>. + </p> + + <p> + In the download script for memtest86plus, make sure to update the checksum that it matches + for the downloaded source tarball. + </p> + + <p> + <a href="#pagetop">Back to top of page</a>. + </p> + + </div> + + <div class="section"> + + <p> + Copyright © 2015 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> |