diff options
Diffstat (limited to 'docs/gnulinux/grub_cbfs.md')
| -rw-r--r-- | docs/gnulinux/grub_cbfs.md | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/docs/gnulinux/grub_cbfs.md b/docs/gnulinux/grub_cbfs.md new file mode 100644 index 00000000..1dd1a983 --- /dev/null +++ b/docs/gnulinux/grub_cbfs.md @@ -0,0 +1,305 @@ +<div class="section"> + +How to replace the default GRUB configuration file on a libreboot system {#pagetop} +======================================================================== + +Libreboot on x86 uses the GRUB +[payload](http://www.coreboot.org/Payloads#GRUB_2) 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. + +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). + +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. + +Here is an excellent writeup about CBFS (coreboot filesystem): +<http://lennartb.home.xs4all.nl/coreboot/col5.html>. + +**This guide is \*only\* for the GRUB payload. If you use the +depthcharge payload, ignore this section entirely.** + +[Back to previous index](./) + +</div> + +<div class="section"> + +Table of Contents +================= + +- [Introduction](#introduction) +- [1st option: don\'t re-flash](#option1_dont_reflash) +- [2nd option: re-flash](#option2_reflash) + - [Acquire the necessary utilities](#tools) + - [Acquiring the correct ROM image](#rom) + - [Extract grubtest from the ROM image](#extract_testconfig) + - [Re-insert the modified grubtest.cfg into the ROM + image](#reinsert_modified_testconfig) + - [Testing](#testing) + - [Final steps](#final_steps) + +</div> + +<div class="section"> + +Introduction +------------ + +Download the latest release from <http://libreboot.org/>\ +**If you downloaded from git, refer to +[../git/\#build\_meta](../git/#build_meta) before continuing.** + +[Back to top of page.](#pagetop) + +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 +[equipment](../install/bbb_setup.html) 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. + +</div> + +<div class="section"> + +1st option: don\'t re-flash {#option1_dont_reflash} +--------------------------- + +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. + +Simply create your custom GRUB configuration and save it to +**/boot/grub/libreboot\_grub.cfg** on the running system. The next time +you boot, GRUB (in libreboot) will automatically switch to this +configuration file. **This means that you do not have to re-flash, +recompile or otherwise modify libreboot at all!** + +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. + +If you want to adapt a copy of the existing *libreboot* GRUB +configuration and use that for the libreboot\_grub.cfg file, then follow +[\#tools](#tools), [\#rom](#rom) and +[\#extract\_testconfig](#extract_testconfig) to get the +***grubtest.cfg***. Rename ***grubtest.cfg*** to +***libreboot\_grub.cfg*** and save it to ***/boot/grub/*** 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); **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.**. + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +2nd option: re-flash {#option2_reflash} +-------------------- + +You can modify what is stored inside the flash chip quite easily. Read +on to find out how. + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Acquire the necessary utilities {#tools} +------------------------------- + +Use ***cbfstool*** and ***flashrom***. There are available in the +*libreboot\_util* release archive, or they can be compiled (see +[../git/\#build\_flashrom](../git/#build_flashrom)). Flashrom is also +available from the repositories:\ +\# **pacman -S flashrom** + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Acquiring the correct ROM image {#rom} +------------------------------- + +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 *libreboot.rom*, so please make sure to adapt. + +ROM images are included pre-compiled in libreboot. You can also dump +your current firmware, using flashrom:\ +\$ **sudo flashrom -p internal -r libreboot.rom**\ +\# **flashrom -p internal -r libreboot.rom**\ +If you are told to specify the chip, add the option **-c {your chip}** +to the command, for example:\ +\# **flashrom -c MX25L6405 -p internal -r libreboot.rom** + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Extract grubtest.cfg from the ROM image {#extract_testconfig} +--------------------------------------- + +You can check the contents of the ROM image, inside CBFS:\ +**\$ cd \.../libreboot\_util/cbfstool** **\$ ./cbfstool libreboot.rom +print** + +The files *grub.cfg* and *grubtest.cfg* 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 *grubtest.cfg*. This is to +reduce the possibility of bricking your device, so DO NOT SKIP THIS! + +Extract grubtest.cfg from the ROM image:\ +**\$ ./cbfstool libreboot.rom extract -n grubtest.cfg -f grubtest.cfg** + +Modify the grubtest.cfg accordingly. + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Re-insert the modified grubtest.cfg into the ROM image {#reinsert_modified_testconfig} +------------------------------------------------------ + +Once your grubtest.cfg is modified and saved, delete the unmodified +config from the ROM image:\ +**\$ ./cbfstool libreboot.rom remove -n grubtest.cfg** + +Next, insert the modified version:\ +**\$ ./cbfstool libreboot.rom add -n grubtest.cfg -f grubtest.cfg -t +raw** + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Testing +------- + +**Now you have a modified ROM. Refer back to +[../install/\#flashrom](../install/#flashrom) for information on how to +flash it.\ +\$ **cd /libreboot\_util** \# **./flash update libreboot.rom**\ +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:\ +\# **./flash forceupdate libreboot.rom**\ +You should see **\"Verifying flash\... VERIFIED.\"** written at the end +of the flashrom output. Once you have done that, shut down and then boot +up with your new test configuration.** + +Choose (in GRUB) the menu entry that switches to grubtest.cfg. If it +works, then your config is safe and you can continue below. + +**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.** + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Final steps {#final_steps} +----------- + +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:\ +\$ **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**\ + +Delete the grub.cfg that remained inside the ROM:\ +**\$ ./cbfstool libreboot.rom remove -n grub.cfg** + +Add the modified version that you just made:\ +**\$ ./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw** + +**Now you have a modified ROM. Again, refer back to +[../install/\#flashrom](../install/#flashrom) 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.** + +[Back to top of page.](#pagetop) + +</div> + +<div class="section"> + +Copyright © 2014, 2015 Leah Rowe <info@minifree.org>\ +Copyright © 2015 Jeroen Quint <jezza@diplomail.ch>\ +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 +[../cc-by-sa-4.0.txt](../cc-by-sa-4.0.txt) + +Updated versions of the license (when available) can be found at +<https://creativecommons.org/licenses/by-sa/4.0/legalcode> + +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. + +</div> |