diff options
Diffstat (limited to 'docs/bsd/grub_cbfs.html')
| -rw-r--r-- | docs/bsd/grub_cbfs.html | 366 |
1 files changed, 0 insertions, 366 deletions
diff --git a/docs/bsd/grub_cbfs.html b/docs/bsd/grub_cbfs.html deleted file mode 100644 index 6e7ba447..00000000 --- a/docs/bsd/grub_cbfs.html +++ /dev/null @@ -1,366 +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>How to replace the default GRUB configuration file on a libreboot system</title> -</head> - -<body> - <div class="section"> - <h1 id="pagetop">How to replace the default GRUB configuration file on a libreboot system</h1> - <p> - Libreboot on x86 uses the GRUB <a href="http://www.coreboot.org/Payloads#GRUB_2">payload</a> - by default, which means that the GRUB configuration file - (where your GRUB menu comes from) is stored directly alongside libreboot - and its GRUB payload executable, inside - the flash chip. In context, this means that installing distributions and managing them - is handled slightly differently compared to traditional BIOS systems. - </p> - <p> - A libreboot (or coreboot) ROM image is not simply "flat"; there is an actual - filesystem inside called CBFS (coreboot filesystem). A utility called 'cbfstool' - allows you to change the contents of the ROM image. In this case, libreboot is configured - such that the 'grub.cfg' and 'grubtest.cfg' files exist directly inside CBFS instead of - inside the GRUB payload 'memdisk' (which is itself stored in CBFS). - </p> - <p> - You can either modify - the GRUB configuration stored in the flash chip, or you can modify a GRUB configuration - file on the main storage which the libreboot GRUB payload will automatically search for. - </p> - <p> - Here is an excellent writeup about CBFS (coreboot filesystem): - <a href="http://lennartb.home.xs4all.nl/coreboot/col5.html">http://lennartb.home.xs4all.nl/coreboot/col5.html</a>. - </p> - <p> - <b>This guide is *only* for the GRUB payload. If you use the depthcharge payload, ignore this section entirely.</b> - </p> - <p> - <a href="index.html">Back to previous index</a> - </p> - </div> - - <div class="section"> - - <h1>Table of Contents</h1> - - <ul> - <li><a href="#introduction">Introduction</a></li> - <li><a href="#option1_dont_reflash">1st option: don't re-flash</a></li> - <li> - <a href="#option2_reflash">2nd option: re-flash</a> - <ul> - <li><a href="#tools">Acquire the necessary utilities</a></li> - <li><a href="#rom">Acquiring the correct ROM image</a></li> - <li><a href="#extract_testconfig">Extract grubtest from the ROM image</a> - <li><a href="#reinsert_modified_testconfig">Re-insert the modified grubtest.cfg into the ROM image</a></li> - <li><a href="#testing">Testing</a> - <li><a href="#final_steps">Final steps</a></li> - </ul> - </li> - </ul> - - </div> - - <div class="section"> - - <h2 id="introduction">Introduction</h2> - - <p> - Download the latest release from - <a href="http://libreboot.org/">http://libreboot.org/</a> - <br/><b>If you downloaded from git, refer to - <a href="../git/index.html#build_meta">../git/index.html#build_meta</a> before continuing.</b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - <p> - There are several advantages to modifying the GRUB configuration stored in CBFS, but - this also means that you have to flash a new libreboot ROM image on your system (some users - feel intimidated by this, to say the least). - Doing so can be risky if not handled correctly, because it can result in a bricked - system (recovery is easy if you have the <a href="../install/bbb_setup.html">equipment</a> - for it, but most people don't). If you aren't up to that then don't worry; it is possible - to use a custom GRUB menu without flashing a new image, by loading a GRUB configuration - from a partition on the main storage instead. - </p> - - - </div> - - <div class="section"> - - <h2 id="option1_dont_reflash">1st option: don't re-flash</h2> - - <p> - By default, GRUB in libreboot is configured to scan all partitions on the main storage - for /boot/grub/libreboot_grub.cfg or /grub/libreboot_grub.cfg(for systems where /boot - is on a dedicated partition), and then use it automatically. - </p> - <p> - Simply create your custom GRUB configuration and save it to <b>/boot/grub/libreboot_grub.cfg</b> - on the running system. The next time you boot, GRUB (in libreboot) will automatically switch to - this configuration file. <b>This means that you do not have to re-flash, recompile or otherwise - modify libreboot at all!</b> - </p> - - <p> - Ideally, your distribution should automatically generate a libreboot_grub.cfg file that is written - specifically under the assumption that it will be read and used on a libreboot system that uses - GRUB as a payload. If your distribution does not do this, then you can try to add that feature - yourself or politely ask someone involved with or otherwise knowledgeable about the distribution - to do it for you. The libreboot_grub.cfg could either contain the full configuration, or it could - chainload another GRUB ELF executable (built to be used as a coreboot payload) that is located in - a partition on the main storage. - </p> - - <p> - If you want to adapt a copy of the existing <i>libreboot</i> GRUB configuration and use that for the libreboot_grub.cfg file, then - follow <a href="#tools">#tools</a>, <a href="#rom">#rom</a> and - <a href="#extract_testconfig">#extract_testconfig</a> to get the <b><i>grubtest.cfg</i></b>. - Rename <b><i>grubtest.cfg</i></b> to <b><i>libreboot_grub.cfg</i></b> and save it to <b><i>/boot/grub/</i></b> - on the running system where it is intended to be used. Modify the file at that location however you see fit, - and then stop reading this guide (the rest of this page is irrelevant to you); <b>in libreboot_grub.cfg on disk, - if you are adapting it based on grub.cfg from CBFS then remove the check for libreboot_grub.cfg otherwise it will loop.</b>. - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="option2_reflash">2nd option: re-flash</h2> - - <p> - You can modify what is stored inside the flash chip quite easily. Read on to find out how. - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - <div class="section"> - <h2 id="tools">Acquire the necessary utilities</h2> - - <p> - Use <b><i>cbfstool</i></b> and <b><i>flashrom</i></b>. There are available in the <i>libreboot_util</i> release archive, - or they can be compiled (see <a href="../git/index.html#build_flashrom">../git/index.html#build_flashrom</a>). - Flashrom is also available from the repositories:<br/> - # <b>pacman -S flashrom</b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="rom">Acquiring the correct ROM image</h2> - - <p> - You can either work directly with one of the ROM images already included in the libreboot ROM archives, or re-use the ROM that - you have currently flashed. For the purpose of this tutorial it is assumed that your ROM image file is named <i>libreboot.rom</i>, - so please make sure to adapt. - </p> - <p> - ROM images are included pre-compiled in libreboot. You can also dump your current firmware, using flashrom:<br/> - $ <b>sudo flashrom -p internal -r libreboot.rom</b><br/> - # <b>flashrom -p internal -r libreboot.rom</b><br/> - If you are told to specify the chip, add the option <b>-c {your chip}</b> to the command, for example:<br/> - # <b>flashrom -c MX25L6405 -p internal -r libreboot.rom</b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="extract_testconfig">Extract grubtest.cfg from the ROM image</h2> - - <p> - You can check the contents of the ROM image, inside CBFS:<br/> - <b>$ cd .../libreboot_util/cbfstool</b> - <b>$ ./cbfstool libreboot.rom print</b> - </p> - - <p> - The files <i>grub.cfg</i> and <i>grubtest.cfg</i> should be present. grub.cfg is loaded by default, - with a menuentry for switching to grubtest.cfg. In this tutorial, you will first modify and test <i>grubtest.cfg</i>. - This is to reduce the possibility of bricking your device, so DO NOT SKIP THIS! - </p> - - <p> - Extract grubtest.cfg from the ROM image:<br/> - <b>$ ./cbfstool libreboot.rom extract -n grubtest.cfg -f grubtest.cfg</b> - </p> - - <p> - Modify the grubtest.cfg accordingly. - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="reinsert_modified_testconfig">Re-insert the modified grubtest.cfg into the ROM image</h2> - - <p> - Once your grubtest.cfg is modified and saved, delete the unmodified config from the ROM image:<br/> - <b>$ ./cbfstool libreboot.rom remove -n grubtest.cfg</b> - </p> - - <p> - Next, insert the modified version:<br/> - <b>$ ./cbfstool libreboot.rom add -n grubtest.cfg -f grubtest.cfg -t raw</b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="testing">Testing</h2> - - <p> - <b> - Now you have a modified ROM. Refer back to <a href="../install/index.html#flashrom">../install/index.html#flashrom</a> for information - on how to flash it.<br/> - $ <b>cd /libreboot_util</b> - # <b>./flash update libreboot.rom</b><br/> - Ocassionally, coreboot changes the name of a given board. If flashrom complains about a board mismatch, but you are sure that you chose the correct ROM image, then run this alternative command:<br/> - # <b>./flash forceupdate libreboot.rom</b><br/> - You should see <b>"Verifying flash... VERIFIED."</b> written at the end of the flashrom output. - Once you have done that, shut down and then boot up with your new test configuration. - </b> - </p> - - <p> - Choose (in GRUB) the menu entry that switches to grubtest.cfg. If it works, then your config is safe and you can continue below. - </p> - - <p> - <b> - If it does not work like you want it to, if you are unsure or sceptical in any way, - then re-do the steps above until you get it right! Do *not* proceed past this point - unless you are 100% sure that your new configuration is safe (or desirable) to use. - </b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <h2 id="final_steps">Final steps</h2> - - <p> - When you are satisfied booting from grubtest.cfg, you can create a copy of grubtest.cfg, called grub.cfg. This is the same except for one difference: - the menuentry 'Switch to grub.cfg' will be changed to 'Switch to grubtest.cfg' and inside it, - all instances of grub.cfg to grubtest.cfg. This is so that the main config still - links (in the menu) to grubtest.cfg, so that you don't have to manually switch to it, in - case you ever want to follow this guide again in the future (modifying the already modified config). From /libreboot_util/cbfstool, do:<br/> - $ <b>sed -e 's:(cbfsdisk)/grub.cfg:(cbfsdisk)/grubtest.cfg:g' -e 's:Switch to grub.cfg:Switch to grubtest.cfg:g' < grubtest.cfg > grub.cfg</b><br/> - </p> - - <p> - Delete the grub.cfg that remained inside the ROM:<br/> - <b>$ ./cbfstool libreboot.rom remove -n grub.cfg</b> - </p> - - <p> - Add the modified version that you just made:<br/> - <b>$ ./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw</b> - </p> - - <p> - <b> - Now you have a modified ROM. Again, refer back to <a href="../install/index.html#flashrom">../install/index.html#flashrom</a> for information - on how to flash it. It's the same method as you used before. Shut down and then boot up with your new configuration. - </b> - </p> - - <p> - <a href="#pagetop">Back to top of page.</a> - </p> - - </div> - - <div class="section"> - - <p> - Copyright © 2014, 2015 Leah Rowe <info@minifree.org><br/> - Copyright © 2015 Jeroen Quint <jezza@diplomail.ch><br/> - Permission is granted to copy, distribute and/or modify this document - under the terms of the Creative Commons Attribution-ShareAlike 4.0 International license - or any later version published by Creative Commons; - - A copy of the license can be found at <a href="../cc-by-sa-4.0.txt">../cc-by-sa-4.0.txt</a> - </p> - - <p> - Updated versions of the license (when available) can be found at - <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode">https://creativecommons.org/licenses/by-sa/4.0/legalcode</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> |