Convert documentation to markdown

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\' &lt; grubtest.cfg &gt;
+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 &lt;info@minifree.org&gt;\
+Copyright © 2015 Jeroen Quint &lt;jezza@diplomail.ch&gt;\
+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>