diff options
Diffstat (limited to 'docs/grub')
| -rw-r--r-- | docs/grub/grubeditor.md | 103 | ||||
| -rw-r--r-- | docs/grub/index.md | 42 |
2 files changed, 122 insertions, 23 deletions
diff --git a/docs/grub/grubeditor.md b/docs/grub/grubeditor.md new file mode 100644 index 00000000..6a6e8c5f --- /dev/null +++ b/docs/grub/grubeditor.md @@ -0,0 +1,103 @@ +GRUB EDITOR +=========== + +Libreboot ROM images now support fluid _grub.cfg_ and _grubtest.cfg_ +configuration editing with the grubeditor.sh script! Instead of manually running +cbfstool to manipulate these configuration files, this script will handle the +work for you so you can focus on actually modifying your GRUB configuration +files to your setup's needs. + +At the time of this writing, grubeditor.sh supports extracting and editing +either the grub.cfg or grubtest.cfg file in any cbfstool-compatible Libreboot +ROM image that contains these files, even ones that have been previously +modified. It can also swap these configuration files in an existing ROM image, +handy if you have a working grubtest.cfg and want to make it the default or if +you broke the main grub.cfg and know that your grubtest.cfg still works. Lastly, +it can also run diff on these two configuration files to show you how they +differ. + +Introduction +============ + +grubeditor.sh takes a number of options, the only one which is required being a +valid Libreboot ROM image that uses the GRUB2 payload and contains both +_grub.cfg_ and _grubtest.cfg_ files. Additional options should come _before_ the +ROM image file on the command line. + +You can call the script the **-h** or **--help** option to view a brief summary +of the options available. Consider this guide a more extensive version of this +screen. + +grubeditor.sh supports extended getopt, which means that all options have both a +short and a long form which respectively begin with a single hyphen and a double +hyphen. You can group together several short options with a single hyphen like +**-ris** (or not, like **-r -i -s**). Long options should be written as +standalone arguments. + +Lastly, you can check which version of grubeditor.sh you are using with the +**-v** or **--version** option. + +Requirements +============ + +grubeditor.sh requires an x86, x86_64, or armv7l environment, since these are +the environments for which cbfstools binaries are provided. Additionally, +grubeditor.sh needs a Bash environment with extended getopt functionality that +can run the **diff** command and write to /tmp. Lastly, the script expects to +live in the top directory of the Libreboot utilities package so it can properly +call cbfstool. + +Chances are that you already meet these requirements if you are on a Linux +environment of the listed architectures and downloaded the Libreboot utilities +package from an official source. If not, it shouldn't be too hard to use a +Linux LiveCD of your choice which provides these essentials. + +Optionally, you should make sure your EDITOR variable is set. Otherwise, +grubeditor.sh will default to using vi, which may not exist on your system. You +can override this default or the contents of your EDITOR variable using the +**-e** or **--editor** command. + +Editing configuration files +=========================== + +Invoked without any arguments except for the ROM image, grubeditor.sh will +attempt to extract the _grubtest.cfg_ file from the provided ROM image and +launch it in your editor of choice. If you make changes to the file, +grubeditor.sh will incorporate your changes into a new ROM image with the same +name in the same directory, except that the new ROM file will end with +".modified". You can then flash this ROM image to your platform's BIOS chip. + +If you would prefer to edit the actual _grub.cfg_ configuration file, use the +**-r** or the **--realcfg** option. Everything else will work the same except +that your editor will open the _grub.cfg_ instead. + +If you would prefer to overwrite your existing ROM image instead of creating a +new one ending in ".modified" use the **-i** or **--inplace** option. +Naturally, you can combine this option with the **-r/--realcfg** option +described above. + +Swapping and diffing grub.cfg and grubtest.cfg +============================================== + +grubeditor.sh supports swapping the _grub.cfg_ and _grubtest.cfg_ configuration +files with the **-s** or **--swap** options. This will create a new ROM image +alongside the existing ROM image ending with ".modified" which has these files +swapped. Naturally, you can request this operation overwrite the existing file +instead using the **-i/--inplace** option. + +Lastly, grubeditor.sh supports comparing _grub.cfg_ and _grubtest.cfg_ files for +differences with the **-d** or **--diffcfg** option. This uses the diff command +by default, but if you want to use another program (e.g. vimdiff), you can +specify it with the **-D** or **--differ** option. Note that this mode is only +intended to show differences in the files and does not support updating the +configs themselves, so any changes you make in an interactive differ will be +ignored. + +Conclusion +========== + +I hope that grubeditor.sh will significantly ease modifying your configuration +files in your Libreboot ROM files. + +Should you find any bugs or want any feature requests, please don't hesitate to +email me or bug me on IRC. diff --git a/docs/grub/index.md b/docs/grub/index.md index f148cc0f..12c86359 100644 --- a/docs/grub/index.md +++ b/docs/grub/index.md @@ -1,28 +1,23 @@ --- title: GRUB payload +x-toc-enable: true ... This section relates to the GRUB payload used in libreboot. -- [Changing the background image in GRUB](#grub_background) -- [Setting font in GRUB](#grub_font) -- [GRUB keyboard layouts](#grub_keyboard) - - [Custom keyboard layout in GRUB](#grub_custom_keyboard) - - [UK Dvorak keyboard layout in GRUB](#grub_ukdvorak_keyboard) - -Changing the background image in GRUB {#grub_background} +Changing the background image in GRUB ===================================== Use cbfstool from libreboot\_util, or libreboot\_src/coreboot/util/cbfstool/ if you want to build from source. -./cbfstool yourrom.rom remove background.png -n background.png\ -./cbfstool yourrom.rom add -f background.png -n background.png -t raw + $ ./cbfstool yourrom.rom remove background.png -n background.png + $ ./cbfstool yourrom.rom add -f background.png -n background.png -t raw When you've done this, re-flash your ROM and you should have a new background at boot time. -Setting font in GRUB (for reference) {#grub_font} +Setting font in GRUB (for reference) ==================================== You don't need to do this unless you would like to change the default @@ -43,27 +38,29 @@ This is a free font that is also contained in GNU+Linux distributions like Debian, Devuan or Parabola. $ cd libreboot\_src/grub + compile grub (the build scripts info on how to do this)\ come back out into libreboot\_src/resources/grub: $ cd ../libreboot\_src/resources/grub/font I took Dejavu Sans Mono from dejavu (included in this version of -libreboot) and did:\ -**\$ ../../../grub/grub-mkfont -o dejavusansmono.pf2 -dejavu-fonts-ttf-2.34/ttf/DejaVuSansMono.ttf** +libreboot) and did: + + $ ../../../grub/grub-mkfont -o dejavusansmono.pf2 dejavu-fonts-ttf-2.34/ttf/DejaVuSansMono.ttf I then added the instructions to 'gen.sh' script in grub-assemble to include resources/grub/dejavusansmono.pf2 in all of the ROM images, at the root of the GRUB memdisk.\ I then added that instructions to the grub.cfg files (to load the -font):\ -**loadfont (memdisk)/dejavusansmono.pf2** +font): + + loadfont (memdisk)/dejavusansmono.pf2 -GRUB keyboard layouts (for reference) {#grub_keyboard} +GRUB keyboard layouts (for reference) ===================================== -Custom keyboard layout in GRUB (for reference) {#grub_custom_keyboard} +Custom keyboard layout in GRUB (for reference) ---------------------------------------------- Keymaps are stored in resources/utilities/grub-assemble/keymap/. @@ -71,9 +68,10 @@ Keymaps are stored in resources/utilities/grub-assemble/keymap/. Example (French Azerty): $ ckbcomp fr > frazerty -\ -Go in grub directory:\ -**cat frazerty | ./grub/grub-mklayout -o frazerty.gkb** + +Go in grub directory: + + $ cat frazerty | ./grub/grub-mklayout -o frazerty.gkb You must make sure that the files are named keymap and keymap.gkb (where 'keymap' can be whatever you want). @@ -87,7 +85,7 @@ The build scripts will automatically see this, and automatically build ROM images with your custom layout (given the name) and include them under bin. Example: **libreboot\_frazerty.rom**. -UK Dvorak keyboard layout in GRUB (for reference) {#grub_ukdvorak_keyboard} +UK Dvorak keyboard layout in GRUB (for reference) ------------------------------------------------- ukdvorak had to be created manually, based on usdvorak. diff them (under @@ -98,8 +96,6 @@ file was created Copyright © 2014 Leah Rowe <info@minifree.org>\ - - 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 |