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/gnulinux/grub_cbfs.html') diff --git a/docs/gnulinux/grub_cbfs.html b/docs/gnulinux/grub_cbfs.html deleted file mode 100644 index 75b1a40..0000000 --- a/docs/gnulinux/grub_cbfs.html +++ /dev/null @@ -1,376 +0,0 @@ - - - - - - - - - How to replace the default GRUB configuration file on a libreboot system - - - -
-

How to replace the default GRUB configuration file on a libreboot system

-

- Libreboot on x86 uses the GRUB payload - 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 -

-
- -
- -

Table of Contents

- - - -
- -
- -

Introduction

- -

- Download the latest release from - http://libreboot.org/ -
If you downloaded from git, refer to - ../git/index.html#build_meta before continuing. -

- -

- Back to top of page. -

- -

- 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 - 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. -

- - -
- -
- -

1st option: don't re-flash

- -

- 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, #rom and - #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.. -

- -

- This is all well and good, but what should you actually put in your GRUB configuration file? - Read grub_config.html for more information. -

- -

- Back to top of page. -

- -
- -
- -

2nd option: re-flash

- -

- You can modify what is stored inside the flash chip quite easily. Read on to find out how. -

- -

- Back to top of page. -

- -
-
-

Acquire the necessary utilities

- -

- Use cbfstool and flashrom. There are available in the libreboot_util release archive, - or they can be compiled (see ../git/index.html#build_flashrom). - Flashrom is also available from the repositories:
- # pacman -S flashrom -

- -

- Back to top of page. -

- -
- -
- -

Acquiring the correct ROM image

- -

- 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. -

- -
- -
- -

Extract grubtest.cfg from the ROM image

- -

- 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. -

- -

- This is all well and good, but what should you actually put in your GRUB configuration file? - Read grub_config.html for more information. -

- -

- Back to top of page. -

- -
- -
- -

Re-insert the modified grubtest.cfg into the ROM image

- -

- 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. -

- -
- -
- -

Testing

- -

- - Now you have a modified ROM. Refer back to ../install/index.html#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. -

- -
- -
- -

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/index.html#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. -

- -
- -
- -

- Copyright © 2014, 2015 Francis Rowe <info@gluglug.org.uk>
- Copyright © 2015 Jeroen Quint <jezza@diplomail.ch>
- 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