diff options
| author | Francis Rowe <info@gluglug.org.uk> | 2015-11-06 22:43:29 +0000 |
|---|---|---|
| committer | Francis Rowe <info@gluglug.org.uk> | 2015-11-07 04:45:09 +0000 |
| commit | 95259e28ef047923258434898113d70c8e544eab (patch) | |
| tree | 1c0501bf4c7df1c31948184dabfc1e7c4c215a6e /docs/maintain/index.html | |
| parent | 707f9383a8189b0054730134340f20709f56f976 (diff) | |
| download | librebootfr-95259e28ef047923258434898113d70c8e544eab.tar.gz librebootfr-95259e28ef047923258434898113d70c8e544eab.zip | |
convert documentation to texinfo
Diffstat (limited to 'docs/maintain/index.html')
| -rw-r--r-- | docs/maintain/index.html | 692 |
1 files changed, 0 insertions, 692 deletions
diff --git a/docs/maintain/index.html b/docs/maintain/index.html deleted file mode 100644 index 2a8cf271..00000000 --- a/docs/maintain/index.html +++ /dev/null @@ -1,692 +0,0 @@ -<!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> - <li> - <a href="#seabios">SeaBIOS</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"> - - <h1 id="seabios">SeaBIOS</h1> - - <p> - Create the SeaBIOS config like so (changed from defaults):<br/> - $ <b>./build config seabiosmodify</b> - </p> -<pre> -General Features -> Build Target -> Build for coreboot (enable) -VGA ROM -> VGA Hardware Type -> coreboot linear framebuffer (enable) -Debugging -> Serial port debugging (enable) -</pre> - - <p> - When updating SeaBIOS, run the following:<br/> - $ <b>./build config seabiosupdate</b><br/> - (this will run <b>make oldconfig</b> on seabios) - </p> - - <p> - Relevant scripts: - </p> - <ul> - <li>resources/scripts/helpers/build/config/seabiosmodify</li> - <li>resources/scripts/helpers/build/config/seabiosupdate</li> - <li>resources/scripts/helpers/download/seabios (change patches used, revision, etc)</li> - <li>resources/scripts/helpers/build/clean/seabios</li> - <li>resources/scripts/helpers/build/module/seabios</li> - </ul> - - </div> - - <div class="section"> - - <p> - Copyright © 2015 Francis Rowe <info@gluglug.org.uk><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> |