From 95259e28ef047923258434898113d70c8e544eab Mon Sep 17 00:00:00 2001 From: Francis Rowe Date: Fri, 06 Nov 2015 17:43:29 -0500 Subject: convert documentation to texinfo --- (limited to 'docs/maintain/index.html') diff --git a/docs/maintain/index.html b/docs/maintain/index.html deleted file mode 100644 index 2a8cf27..0000000 --- a/docs/maintain/index.html +++ /dev/null @@ -1,692 +0,0 @@ - - - - - - - - - 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. -

- -
- -
- -

SeaBIOS

- -

- Create the SeaBIOS config like so (changed from defaults):
- $ ./build config seabiosmodify -

-
-General Features -> Build Target -> Build for coreboot (enable)
-VGA ROM -> VGA Hardware Type -> coreboot linear framebuffer (enable)
-Debugging -> Serial port debugging (enable)
-
- -

- When updating SeaBIOS, run the following:
- $ ./build config seabiosupdate
- (this will run make oldconfig on seabios) -

- -

- Relevant scripts: -

- - -
- -
- -

- Copyright © 2015 Francis Rowe <info@gluglug.org.uk>
- 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 v0.9.1