From f3bb8940d5cf2c9af03007f3a7d9dc6a3cb7dc55 Mon Sep 17 00:00:00 2001 From: Julian Mehne Date: Fri, 27 Feb 2015 00:51:24 +0100 Subject: [PATCH] docs/gnulinux/grub_cbfs.html: Improve structure. - Improve structure so that optional parts are clearer. - Add note about where to find the executables. - Add short explanation of the ROM names. - Copy grubtest.cfg to grubtest_vanilla.cfg before doing any modifications. --- docs/gnulinux/grub_cbfs.html | 182 ++++++++++++++++++++++++++++++------------- 1 file changed, 128 insertions(+), 54 deletions(-) diff --git a/docs/gnulinux/grub_cbfs.html b/docs/gnulinux/grub_cbfs.html index fe961ea..3de8f7b 100644 --- a/docs/gnulinux/grub_cbfs.html +++ b/docs/gnulinux/grub_cbfs.html @@ -18,7 +18,7 @@ Libreboot 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 it's GRUB payload executable, inside + 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.

@@ -26,7 +26,7 @@ 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 exists directly inside CBFS instead of + 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).

@@ -49,21 +49,32 @@

@@ -82,12 +93,6 @@

Back to top of page.

- - - -
- -

Don't want to flash a new ROM image?

There are several advantages to modifying the GRUB configuration stored in CBFS, but @@ -100,6 +105,13 @@ from a partition on the main storage instead.

+ +
+ +
+ +

Option A: don't flash a new ROM

+

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 @@ -139,17 +151,58 @@

+ +

Option B: flash a new ROM

+ +

+ Alternatively to editing the GRUB configuration file on your disk, you can also change the configuration that is + stored in the CBFS on the flash chip. +

+ +

+ Back to top of page. +

+ +
+
+

Get the tools ready

-

Build 'cbfstool' from source

+

+ You will need to use the cbfstool, rmodtool and flashrom tools. + You can either use the pre-compiled binaries provided by the binary release of libreboot, or build the tools + yourself from source from the libreboot source code. +

+ +
+

Locate the tools in the binary release

- If you are working with libreboot_src, then you can run make command in - libreboot_src/coreboot/util/cbfstool to build the cbfstool and rmodtool - executable. + If you are working with the binary release libreboot_util, you will find the cbfstool and + rmodtool binaries under ./cbfstool/{architecture}/ , where {architecture} refers to your + hardware name for which your current running kernel is compiled for. You can find it by running: +
+ $ uname -m +

+

+ The flashrom binary is located under ./flashrom/{architecture}/

- Alternatively if you are working with libreboot_util, you will find binaries under ./cbfstool/ + Whenever one of the tools is used in a command in this tutorial, it will be called as, e.g., ./cbfstool
+ Please adapt the paths accordingly (e.g.: cbfstool/i686/cbfstool).

+
+ +
+

Build the tools from source

+ +

+ If you are working with libreboot_src, then you can run make command in + libreboot_src/coreboot/util/cbfstool to build the cbfstool and rmodtool + executables. See ../git/index.html#build_flashrom for + instructions on how to build flashrom. + +

+

Back to top of page. @@ -162,21 +215,36 @@

Which ROM image should I use?

- You can work directly with one of the ROM images already included in the libreboot ROM archives. For the purpose of - this tutorial it is assumed that your ROM image file is named libreboot.rom, so please make sure to adapt. + 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.

-

- If you want to re-use the ROM that you currently have flashed (and running) then see - ../git/index.html#build_flashrom - and then run:
- $ sudo ./flashrom -p internal -r libreboot.rom
- Notice that this is using "-r" (read) instead of "-w" (write). - This will create a dump (copy) of your current firmware and name it libreboot.rom. - You need to take ownership of the file. For example:
- $ sudo chown yourusername:yourusername libreboot.rom
- # chown yourusername:yourusername libreboot.rom -

+
+

Use one of the provided ROM images

+

+ All ROMs are located under ./bin/{computer_model}/ . Make a working copy of the ROM you want to use: +
+ $ cp ./bin/{computer_model}/{computer_model}_{keyboard_layout}_{mode}.rom libreboot.rom +
+ {keyboard_layout} defines the keyboard layout that will be available on the GRUB console. This might be important + if you protect GRUB with a password later on and want to insert non-ASCII characters. + {mode} can be vesafb or txtmode and starts GRUB with a background image or in text mode. +

+
+ +
+

Re-use the currently flashed ROM image

+

+ If you want to re-use the ROM that you currently have flashed (and running) and then run:
+ $ sudo ./flashrom -p internal -r libreboot.rom
+ Notice that this is using "-r" (read) instead of "-w" (write). + This will create a dump (copy) of your current firmware and name it libreboot.rom. + You need to take ownership of the file. For example:
+ $ sudo chown yourusername:yourusername libreboot.rom
+ # chown yourusername:yourusername libreboot.rom +

+

If you currently have flashed a ROM image from an older version, it is recommended to update first: @@ -200,8 +268,8 @@

The libreboot.rom file contains your grub.cfg and grubtest.cfg 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). + grub.cfg will load first, but it has a menu entry for switching to the copy (grubtest.cfg). + Thus, you should extract, modify and re-insert the grubtest.cfg first. This reduces your chance of making a mistake that could make your machine unbootable (or very hard to boot).

@@ -211,7 +279,12 @@

- Now you have a grubtest.cfg in cbfstool directory. Edit it however you wish. + Make a copy of the original file, before you modify it:
+ $ cp grubtest.cfg grubtest_vanilla.cfg +

+ +

+ Now you have a grubtest.cfg in the cbfstool directory. Edit it however you wish.

@@ -221,15 +294,14 @@

+

Example modifications for grubtest.cfg

-
- -

Example modifications for grubtest.cfg

+

+ These are some common examples of ways in which the grubtest.cfg file can be modified. +

-

- These are some common examples of ways in which the grubtest.cfg file can be modified. -

+

Trisquel GNU/Linux-libre

@@ -310,13 +382,15 @@ There are lots of possible variations so please try to adapt.

-

Parabola GNU/Linux-libre

+
-

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

+
+

Parabola GNU/Linux-libre

+

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

@@ -457,7 +531,7 @@

- Copyright © 2014, 2015 Francis Rowe <address@hidden>
+ Copyright © 2014, 2015 Francis Rowe <address@hidden>, Julian Mehne
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 ../license.txt.

-- 2.3.1