diff options
Diffstat (limited to 'docs/bsd/grub_cbfs.html')
| -rw-r--r-- | docs/bsd/grub_cbfs.html | 366 |
1 files changed, 366 insertions, 0 deletions
diff --git a/docs/bsd/grub_cbfs.html b/docs/bsd/grub_cbfs.html new file mode 100644 index 00000000..6e7ba447 --- /dev/null +++ b/docs/bsd/grub_cbfs.html @@ -0,0 +1,366 @@ +<!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> |