Documentation: *major* cleanup.

Cleanup was long overdue. Old structure was messy and inefficient.
author: Francis Rowe <info@gluglug.org.uk> 2014-11-05 20:52:36 (EST)
committer: Francis Rowe <info@gluglug.org.uk> 2014-11-05 20:52:36 (EST)
commit: 8b2219bfa2da36e7809588ef723a10483a6e137f (patch)
tree: 8c4d74b9efbdabc1a2604b8cbd508c006c225241 /docs/gnulinux/grub_cbfs.html
parent: 7429bdcdbb4fc51c61897115112468642afeecfc (diff)
download: libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.zip
libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.tar.gz
libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.tar.bz2
1 files changed, 400 insertions, 0 deletions
diff --git a/docs/gnulinux/grub_cbfs.html b/docs/gnulinux/grub_cbfs.html
new file mode 100644
index 0000000..c9a0f45
--- /dev/null
+++ b/docs/gnulinux/grub_cbfs.html
@@ -0,0 +1,400 @@
+<!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>Libreboot documentation: GRUB menu</title>
+</head>
+
+<body>
+	<header>
+		<h1 id="pagetop">How to change your default GRUB menu</h1>
+		<aside>Or <a href="index.html">back to main index</a></aside>
+	</header>
+
+	<p>
+		Libreboot 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 it's 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 &quot;flat&quot;; 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 exists directly inside CBFS instead of 
+		inside the GRUB payload's 'memdisk' (which is itself stored in CBFS).
+	</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>
+
+<hr/>
+
+	<h2>Table of Contents</h2>
+
+		<ul>
+			<li><a href="#getting_started">Getting started</a></li>
+			<li><a href="#build_cbfstool">Build 'cbfstool' from source</a></li>
+			<li><a href="#which_rom">Which ROM image should I use?</a></li>
+			<li><a href="#extract_grubtest">Extract grubtest from the ROM image</a>
+			<li>
+				<a href="#example_modifications">Example modifications for <i>grubtest.cfg</i></a>
+				<ul>
+					<li><a href="#example_modifications_trisquel">Trisquel GNU/Linux-libre</a></li>
+					<li><a href="#example_modifications_parabola">Parabola GNU/Linux-libre</a></li>
+				</ul>
+			</li>
+			<li><a href="#reinsert_modified_grubtest">Re-insert the modified grubtest.cfg into the ROM image</a></li>
+			<li><a href="#test_it">Test it!</a>
+			<li><a href="#final_steps">Final steps</a></li>
+			<li><a href="#troubleshooting">Troubleshooting</a></li>
+		</ul>
+
+<hr/>
+
+	<h2 id="getting_started">Getting started</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="../git/index.html#build_dependencies">Install the build dependencies</a>.
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<h2 id="build_cbfstool">Build 'cbfstool' from source</h2>
+
+		<p>
+			If you are working with libreboot_src, then you can run <b><i>make</i></b> command in 
+			libreboot_src/coreboot/util/cbfstool to build the <b><i>cbfstool</i></b> and <b><i>rmodtool</i></b>
+			executable.
+		</p>
+		<p>
+			Alternatively if you are working with libreboot_bin, then you can run <b><i>./builddeps-cbfstool</i></b>
+			command inside libreboot_bin/; a <b><i>cbfstool</i></b> and <b><i>rmodtool</i></b>
+			executable will appear under libreboot_bin/
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<h2 id="which_rom">Which ROM image should I use?</h2>
+
+		<p>
+			You can work directly with one of the ROM's already included in the libreboot ROM archives. For the purpose of 
+			this tutorial it is assumed that your ROM is named <i>libreboot.rom</i> so please make sure to adapt.
+		</p>
+
+		<p>
+			If you want to re-use the ROM that you currently have flashed (and running) then see 
+			<a href="../git/index.html#build_flashrom">../git/index.html#build_flashrom</a>
+			and then run:<br/>
+			<b>$ sudo ./flashrom -p internal -r libreboot.rom</b><br/>
+			Notice that this is using <b>&quot;-r&quot;</b> (read) instead of <b>&quot;-w&quot;</b> (write). 
+			This will create a dump (copy) of your current firmware and name it <b>libreboot.rom</b>. 
+			You need to take ownership of the file. For example:<br/>
+			<b>$ sudo chown yourusername:yourusername libreboot.rom</b><br/>
+			<b># chown yourusername:yourusername libreboot.rom</b>
+		</p>
+
+		<p>
+			If you currently have flashed a ROM image from an older version, it is recommended to update first: 
+			basically, modify one of the latest ROM's and then flash it.
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<h2 id="extract_grubtest">Extract grubtest.cfg from the ROM image</h2>
+
+		<p>
+			Display contents of ROM:<br/>
+			<b>$ ./cbfstool libreboot.rom print</b>
+		</p>
+
+		<p>
+			The libreboot.rom file contains your <i>grub.cfg</i> and <i>grubtest.cfg</i> files. 
+			You should extract, modify and re-insert the copy first. grub.cfg will load first, 
+			but it has a menu entry for switching to the copy (grubtest.cfg).
+			This reduces your chance of making a mistake that could make your machine unbootable (or very hard to boot).
+		</p>
+
+		<p>
+			Extract grubtest.cfg from the ROM image:<br/>
+			<b>$ ./cbfstool libreboot.rom extract -n grubtest.cfg -f grubtest.cfg</b>
+		</p>
+
+		<p>
+			Now you have a grubtest.cfg in cbfstool directory. Edit it however you wish.
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<div class="important">
+
+		<h2 id="example_modifications">Example modifications for <i>grubtest.cfg</i></h2>
+
+			<p>
+				These are some common examples of ways in which the grubtest.cfg file can be modified.
+			</p>
+
+			<h3 id="example_modifications_trisquel">Trisquel GNU/Linux-libre</h3>
+
+				<p>
+					As an example, on my test system in /boot/grub/grub.cfg (on the HDD/SSD) I see for the main menu entry:
+				</p>
+				<ul>
+						<li><b>linux	/boot/vmlinuz-3.15.1-gnu.nonpae root=UUID=3a008e14-4871-497b-95e5-fb180f277951 ro   crashkernel=384M-2G:64M,2G-:128M quiet splash $vt_handoff</b></li>
+						<li><b>initrd	/boot/initrd.img-3.15.1-gnu.nonpae</b></li>
+				</ul>
+
+				<p>
+					<b>ro</b>, <b>quiet</b>, <b>splash</b>, <b>crashkernel=384M-2G:64M,2G-:128M</b> and 
+					<b>$vt_handoff</b> can be safely ignored.
+				</p>
+
+				<p>
+					I use this to get my partition layout:<br/>
+					$ <b>lsblk</b>
+				</p>
+
+				<p>
+					In my case, I have no /boot partition, instead /boot is on the same partition as / on sda1. 
+					Yours might be different. In GRUB terms, sda means ahci0. 1 means msdos1, or gpt1, depending 
+					on whether I am using MBR or GPT partitioning. Thus, /dev/sda1 is GRUB is (ahci0,msdos1) or 
+					(ahci0,gpt1). In my case, I use MBR partitioning so it's (ahci0,msdos1).
+					'msdos' is GRUB's name simply because this partitioning type is traditionally used by MS-DOS. 
+					It doesn't mean you have a proprietary OS.
+				</p>
+
+				<p>
+					Trisquel doesn't keep the filenames of kernels consistent, instead it keeps old kernels and 
+					new kernel updates are provided with the version in the filename. This can make GRUB payload 
+					a bit tricky. Fortunately, there are symlinks /vmlinuz and /initrd.img
+					so if your /boot and / are on the same partition, you can set GRUB to boot from that. 
+					These are also updated automatically when installing kernel updates from your distributions 
+					apt-get repositories.
+					<b>
+						Note: when using <a href="http://jxself.org/linux-libre">jxself kernel releases</a>, 
+						these are not updated at all and you have to update them manually.
+					</b>
+				</p>
+
+				<p>
+					For the GRUB payload's grubtest.cfg (in the 'Load Operating System' menu entry), we therefore have (in this example):<br/>
+					<b>set root='ahci0,msdos1'</b><br/>
+					<b>linux /vmlinuz root=UUID=3a008e14-4871-497b-95e5-fb180f277951</b><br/>
+					<b>initrd /initrd.img</b>
+				</p>
+
+				<p>
+					Optionally, you can convert the UUID to it's real device name, for example /dev/sda1 in this case.
+					sdX naming isn't very reliable, though, which is why UUID is used for most distributions.
+				</p>
+
+				<p>
+					Alternatively, if your /boot is on a separate partition then you cannot rely on the /vmlinuz and /initrd.img symlinks.
+					Instead, go into /boot and create your own symlinks (update them manually when you install a new kernel update).<br/>
+					$ <b>sudo -s</b><br/>
+					# <b>cd /boot/</b><br/>
+					# <b>rm -rf vmlinuz initrd.img</b><br/>
+					# <b>ln -s <u>kernel</u> ksym</b><br/>
+					# <b>ln -s <u>initrd</u> isym</b><br/>
+					# <b>exit</b>
+				</p>
+
+				<p>
+					Replace the underlined <b>kernel</b> and <b>initrd</b> filenames above with the actual filenames, of course.
+				</p>
+
+				<p>
+					Then your grubtest.cfg menu entry (for payload) becomes like that, for example if / was on sda2 and /boot was on sda1:<br/>
+					<b>set root='ahci0,msdos1'</b><br/>
+					<b>linux /ksym root=/dev/sda2</b><br/>
+					<b>initrd /isym</b>
+				</p>
+
+				<p>
+					There are lots of possible variations so please try to adapt.
+				</p>
+
+			<h3 id="example_modifications_parabola">Parabola GNU/Linux-libre</h3>
+
+				<p>
+					You can basically adapt the above. Note however that Parabola does not keep old kernels still installed, and the file names 
+					are always consistent, so you don't need to boot from symlinks, you can just use the real thing directly.
+				</p>
+
+	</div>
+
+	<p>
+		<a href="#pagetop">Back to top of page.</a>
+	</p>
+
+<hr/>
+
+	<h2 id="reinsert_modified_grubtest">Re-insert the modified grubtest.cfg into the ROM image</h2>
+
+		<p>
+			Delete the grubtest.cfg that remained inside the ROM:<br/>
+			<b>$ ./cbfstool libreboot.rom remove -n grubtest.cfg</b>
+		</p>
+
+		<p>
+			Display ROM contents and now you see grubtest.cfg no longer exists there:<br/>
+			<b>$ ./cbfstool libreboot.rom print</b>
+		</p>
+
+		<p>
+			Add the modified version that you just made:<br/>
+			<b>$ ./cbfstool libreboot.rom add -n grubtest.cfg -f grubtest.cfg -t raw</b>
+		</p>
+
+		<p>
+			Now display ROM contents again and see that it exists again:<br/>
+			<b>$ ./cbfstool libreboot.rom print</b>
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<h2 id="test_it">Test it!</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. 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>
+
+<hr/>
+
+	<h2 id="final_steps">Final steps</h2>
+
+		<p>
+			Create a copy of grubtest.cfg, called grub.cfg, which is the same except for one difference: 
+			change the menuentry 'Switch to grub.cfg' to 'Switch to grubtest.cfg' and inside it,
+			change 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)<br/>
+			$ <b>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</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>
+			Display ROM contents and now you see grub.cfg no longer exists there:<br/>
+			<b>$ ./cbfstool libreboot.rom print</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>
+			Now display ROM contents again and see that it exists again:<br/>
+			<b>$ ./cbfstool libreboot.rom print</b>
+		</p>
+
+		<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. Once you have done that, shut down and then boot up with your new configuration.
+			</b>
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<h2 id="troubleshooting">Troubleshooting</h2>
+
+		<p>
+			A user reported that segmentation faults occur with cbfstool 
+			when using this procedure depending on the size of the grub.cfg being re-insterted. 
+			In his case, a minimum size of 857 bytes was required. This could (at the time of 
+			this release) be a bug in cbfstool that should be investigated with the coreboot 
+			community. If cbfstool segfaults, then keep this in mind. 'strace' (or gdb? clang?) 
+			could be used for debugging. This was in libreboot 5th release (based on coreboot 
+			from late 2013), and I'm not sure if the issue perists in the current releases.
+			I have not been able to reproduce it. strace (from that user) is here: 
+			<a href="cbfstool_libreboot5_strace">cbfstool_libreboot5_strace</a>. 
+			The issue has been reported by a few users, so it does not happen all the time: 
+			this bug (if it still exists) could (should) be reproduced.
+		</p>
+
+		<p>
+			<a href="#pagetop">Back to top of page.</a>
+		</p>
+
+<hr/>
+
+	<p>
+		Copyright &copy; 2014 Francis Rowe &lt;info@gluglug.org.uk&gt;<br/>
+		This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions.
+		A copy of the license can be found at <a href="../license.txt">../license.txt</a>.
+	</p>
+
+	<p>
+		This document is distributed in the hope that it will be useful,
+		but WITHOUT ANY WARRANTY; without even the implied warranty of
+		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See <a href="../license.txt">../license.txt</a> for more information.
+	</p>
+
+</body>
+</html>
author	Francis Rowe <info@gluglug.org.uk>	2014-11-05 20:52:36 (EST)
committer	Francis Rowe <info@gluglug.org.uk>	2014-11-05 20:52:36 (EST)
commit	8b2219bfa2da36e7809588ef723a10483a6e137f (patch)
tree	8c4d74b9efbdabc1a2604b8cbd508c006c225241 /docs/gnulinux/grub_cbfs.html
parent	7429bdcdbb4fc51c61897115112468642afeecfc (diff)
download	libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.zip libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.tar.gz libreboot-8b2219bfa2da36e7809588ef723a10483a6e137f.tar.bz2