From c679b19f0b0d95f587b3836c7bf867a932d3df28 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Mon, 22 Aug 2016 10:22:04 +0100 Subject: actually add the documentation directory. (I forgot git add in last commit) --- docs/maintain/index.html | 656 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 656 insertions(+) create mode 100644 docs/maintain/index.html (limited to 'docs/maintain/index.html') 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 @@ + + + + + + + + + Maintaining libreboot + + + + +
+ +

Maintaining libreboot

+ +

+ This section relates to maintaining libreboot. +

+

+ Do not follow anything here to the letter; is it only a rough guide + representing how libreboot is maintained (for reference). +

+

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

+ + + +

+ Or Back to main index. +

+ +
+ +
+ +

Overview

+ +

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

+

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

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating coreboot-libre

+ +

+ NOTE: it helps to own all libreboot-compatible systems here, + or have reliable (and fast) access to a team of testers. +

+ +

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

+ +

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

+ +

+ Open these files in your editor (you will most likely be editing them): +

+ + +

+ If you already had a coreboot/ directory in your libreboot + tree, delete it:
+ $ rm -Rf coreboot/ +

+ +

+ Firstly, download coreboot. Do not use ./download coreboot + for this, just clone coreboot, as it does in that script, like so:
+ $ git clone http://review.coreboot.org/coreboot +

+ +

+ $ cd coreboot/
+ Get the ID of the latest commit in this clone, by reading the commit ID using + e.g.:
+ $ git log
+ In resources/scripts/helpers/download/coreboot you will + find a line that says git reset --hard 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. +

+

+ You must also checkout the vboot submodule:
+ $ git submodule update --init --checkout -- 3rdparty/vboot/ +

+

+ Delete the .git* resources. For example:
+ $ rm -Rf .git* 3rdparty/*/.git*
+ ...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:
+ $ cd ../ +

+ +

+ Check all coreboot file names/paths in deblob; if any + of them no longer exist at that name/path in the coreboot tree that you downloaded, + delete the reference(s) in deblob. +

+ +

+ Check all coreboot file names/paths in nonblobs; if + any of them no longer exist at that name/path in the coreboot tree that you downloaded, + delete the reference in nonblobs. +

+ +

+ Now, back in the main root directory of libreboot (git repository), + run the deblob script. This is to prevent the findblobs + scripts from finding the blobs that are already deleted + when running the deblob script. Like so:
+ $ ./resources/utilities/coreboot-libre/deblob +

+ +

+ Now search for new blobs:
+ $ cd resources/utilities/coreboot-libre/
+ $ ./findblobs
+ WARNING: this will take a *long* 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 nonblobs. +

+ +

+ Once the findblobs script has finished, check the file + tocheck (from the root, this will be resources/utilities/coreboot-libre/tocheck). + These are the files detected as blobs; some might be blobs, some not. + The findblobs 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. +

+ + +

+ 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:
+ $ cd ../../../ +

+ +

+ Now delete the coreboot directory:
+ $ rm -Rf coreboot/ +

+ +

+ 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 resources/scripts/helpers/download/coreboot + accordingly. Anyway, download coreboot like so:
+ $ ./download coreboot +

+ +

+ 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:
+ http://www.coreboot.org/Git. +

+ +

+ Update all configs:
+ $ ./build config grubupdate
+ $ ./build config dcupdate
+ This simply takes all of the coreboot .config files from + resources/libreboot/config/ and does make oldconfig + on them. It usually works. If it doesn't, you'll need to recreate + those configs from scratch using ./build config grubreplace + or ./build config dcreplace (optionally + add a config name), or ./build config grubmodify + or ./build config dcmodify (ditto) + (see ../git/index.html#config) +

+ +

+ Finally, build *all* ROM images using the instructions at + ../git/index.html, to verify + that everything still builds. +

+ +

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

+ +

+ 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: + http://www.coreboot.org/Git + and then re-update coreboot (or apply patches from upstream). +

+ +

+ You should also test the resulting ROM images from building + with the new or modified coreboot revision. +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Adding a new board to libreboot

+ +

+ 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):
+ $ ./build config grubreplace payload/boardname
+ Alternatively, for depthcharge payload:
+ $ ./build config dcreplace payload/boardname +

+ +

+ This can also be used for replacing an existing config. +

+ +

+ Configure the board. Make sure to add the steps to the config section + in ../git/index.html. +

+ +

+ When you're done, the config will be stored in resources/libreboot/config/. + Now build-test it and then check that it actually works. +

+ +

+ The following scripts may also need to be modified before building: + resources/scripts/helpers/build/roms/withgrub and + resources/scripts/helpers/build/roms/helper +

+ +

+ The following can be used when updating coreboot-libre (GRUB payload):
+ $ ./build config grubupdate
+ You must also do this for boards that use the depthcharge payload:
+ $ ./build config dcupdate
+ (adding a board name on the end is optional, for either of these) +

+ +

+ The following can be used if you want to modify an existing + configuration (GRUB payload):
+ $ ./build config grubmodify
+ For those boards which use the depthcharge payload:
+ $ ./build config dcmodify
+ (adding a board name on the end is optional) +

+ +

+ Examples (GRUB payload):
+ $ ./build config grubmodify x60
+ $ ./build config grubreplace x60
+ $ ./build config grubupdate x60
+ $ ./build config grubmodify kfsn4-dre
+ $ ./build config grubreplace kfsn4-dre
+ $ ./build config grubupdate kfsn4-dre
+

+

+ Examples (depthcharge payload):
+ $ ./build config dcmodify veyron_speedy
+ $ ./build config dcreplace veyron_speedy
+ $ ./build config dcupdate veyron_speedy +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Add/remove/modify patches in coreboot-libre

+ +

+ Under resources/scripts/helpers/download/coreboot you can find + the instructions used for patching coreboot. +

+ +

+ Modify the commit ID on the git reset --hard 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 git am + (you can get the diff by using git-format-patch). +

+ +

+ When you're done, simply download coreboot again:
+ $ ./download coreboot +

+ +

+ Finally, re-build the parts from coreboot that are used + by the build system (also builds GCC):
+ $ ./build module coreboot +

+ +

+ 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 + resources/scripts/helpers/build/module/coreboot + except for the part that builds GCC. + Only do this if the version is correct. +

+ +

+ You should also test the resulting ROM images from building + with the new or modified coreboot revision. +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating GRUB

+ +

+ $ rm -Rf grub/
+ $ git clone git://git.savannah.gnu.org/grub.git
+ $ cd grub/
+ $ git log +

+ +

+ Open the file resources/scripts/helpers/download/grub and + replace the commit ID on the line that performs git reset --hard + with the commit ID of the GRUB revision that you just downloaded. +

+ +

+ $ cd ../
+ $ ./download grub +

+ +

+ If it fails because of merge conflicts, you'll need to re-base + or (as appropriate) remove the offending patch(es) in + resources/scripts/helpers/download/grub. +

+ +

+ Finally, verify that it will build:
+ $ ./build module grub +

+ +

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

+ +

+ Back to top of page. +

+ +
+ +
+ +

Change how the GRUB payload (grub.elf) is built (utility: grub-assemble)

+ +

+ Look in resources/utilities/grub-assemble/. +

+ +

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

+ +

+ modules.conf defines which modules will be included in the GRUB + ELF executable. +

+ +

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

+ +

+ Back to top of page. +

+ +
+ +
+ +

Modify the configuration used in GRUB

+ +

+ Look in resources/scripts/helpers/build/roms/withgrub to + see how the GRUB configuration files are generated. +

+ +

+ You might need to modify this. You can also modify the + default configuration by making changes to the files + under resources/grub/config/ +

+ +

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

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating depthcharge

+ +

+ The script to download depthcharge is: resources/scripts/helpers/download/depthcharge. +

+ +

+ Patches are in resources/depthcharge/patch/. +

+ +

+ The configuration used for depthcharge is located in depthcharge/board. + Each board has a defconfig Kconfig configuration and a fmap.dts 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. +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating flashrom

+ +

+ Modify these files: resources/scripts/helpers/download/flashrom + and resources/scripts/helpers/build/module/flashrom. +

+ +

+ Patches are in resources/flashrom/patch/ +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating bucts

+ +

+ bucts doesn't really need updating, but the patches are + in resources/bucts/patch, the download script + is resources/scripts/helpers/download/bucts and + the build script is resources/scripts/helpers/build/module/bucts. +

+ +

+ Back to top of page. +

+ +
+ +
+ +

Updating MemTest86+

+ +

+ MemTest86+ doesn't really need updating, but the patches are + in resources/memtest86plus/patch, the download script + is resources/scripts/helpers/download/memtest86plus and + the build script is resources/scripts/helpers/build/module/memtest86plus. +

+ +

+ In the download script for memtest86plus, make sure to update the checksum that it matches + for the downloaded source tarball. +

+ +

+ Back to top of page. +

+ +
+ +
+ +

+ Copyright © 2015 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