GNU GRUB developer manual ¶

2.1 Naming Conventions ¶

All global symbols (i.e. functions, variables, types, and macros) must have the prefix grub_ or GRUB_. The all capital form is used only by macros.

2.2 Functions ¶

If a function is global, its name must be prefixed with grub_ and must consist of only small letters. If the function belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for file systems, its name is prefixed with grub_fs_. If a function is for FAT file system but not for all file systems, its name is prefixed with grub_fs_fat_. The hierarchy is noted this way.

After a prefix, a function name must start with a verb (such as get or is). It must not be a noun. Some kind of abbreviation is permitted, as long as it wouldn’t make code less readable (e.g. init).

If a function is local, its name may not start with any prefix. It must start with a verb.

2.3 Variables ¶

The rule is mostly the same as functions, as noted above. If a variable is global, its name must be prefixed with grub_ and must consist of only small letters. If the variable belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for dynamic loading, its name is prefixed with grub_dl_. If a variable is for ELF but not for all dynamic loading systems, its name is prefixed with grub_dl_elf_.

After a prefix, a variable name must start with a noun or an adjective (such as name or long) and it should end with a noun. Some kind of abbreviation is permitted, as long as it wouldn’t make code less readable (e.g. i18n).

If a variable is global in the scope of a single file (i.e. it is declared with static), its name may not start with any prefix. It must start with a noun or an adjective.

If a variable is local, you may choose any shorter name, as long as it wouldn’t make code less readable (e.g. i).

2.4 Types ¶

The name of a type must be prefixed with grub_ and must consist of only small letters. If the type belongs to a specific function module, the name must also be prefixed with the module name. For example, if a type is for OS loaders, its name is prefixed with grub_loader_. If a type is for Multiboot but not for all OS loaders, its name is prefixed with grub_loader_linux_.

The name must be suffixed with _t, to emphasize the fact that it is a type but not a variable or a function.

2.5 Macros ¶

If a macro is global, its name must be prefixed with GRUB_ and must consist of only large letters. Other rules are the same as functions or variables, depending on whether a macro is used like a function or a variable.

2.6 Comments ¶

All comments shall be C-style comments, of the form ‘/* … */’. A comment can be placed immediately preceding the entity it describes or it can be placed together with code, variable declarations, or other non-comment entities. However, it is recommended to not mix various forms especially in types/structs descriptions.

Acceptable:

/* The page # that is the front buffer. */
int displayed_page;

int render_page; /* The page # that is the back buffer. */

2.7 Multi-Line Comments ¶

Comments spanning multiple lines shall be formatted with all lines after the first aligned with the first line. Asterisk characters should be repeated at the start of each subsequent line.

Acceptable:

/*
 * This is a comment
 * which spans multiple lines.
 * It is long.
 */

Unacceptable:

/* This is a comment
   which spans multiple lines.
   It is long. */

/*
 * This is a comment
 * which spans multiple lines.
 * It is long. */

/* This is a comment
 * which spans multiple lines.
 * It is long.
 */

In particular first unacceptable form makes comment difficult to distinguish from the code itself. Especially if it contains the code snippets and/or is long. So, its usage is disallowed.

4.1 Getting started ¶

• Always use latest GRUB 2 source code. So get that first.

  For developers it is recommended always to use the newest development version of GRUB 2. If development takes a long period of time, please remember to keep in sync with newest developments regularly so it is much easier to integrate your change in the future. GRUB 2 is being developed in a GIT repository.

  Please check Savannah’s GRUB project page for details how to get newest git: GRUB 2 git Repository

• Compile it and try it out.

  It is always good idea to first see that things work somehow and after that to start to implement new features or develop fixes to bugs.

• Study the code.

  There are sometimes odd ways to do things in GRUB 2 code base. This is mainly related to limited environment where GRUB 2 is being executed. You usually do not need to understand it all so it is better to only try to look at places that relates to your work. Please do not hesitate to ask for help if there is something that you do not understand.

• Develop a new feature.

  Now that you know what to do and how it should work in GRUB 2 code base, please be free to develop it. If you have not so far announced your idea on grub-devel mailing list, please do it now. This is to make sure you are not wasting your time working on the solution that will not be integrated to GRUB 2 code base.

  You might want to study our coding style before starting development so you do not need to change much of the code when your patch is being reviewed. (see Coding style)

  For every accepted patch there has to exist a ChangeLog entry. Our ChangeLog consist of changes within source code and are not describing about what the change logically does. Please see examples from previous entries.

  Also remember that GRUB 2 is licensed under GPLv3 license and that usually means that you are not allowed to copy pieces of code from other projects. Even if the source project’s license would be compatible with GPLv3, please discuss it beforehand on grub-devel mailing list.

• Test your change.

  Test that your change works properly. Try it out a couple of times, preferably on different systems, and try to find problems with it.

• Publish your change.

  When you are happy with your change, first make sure it is compilable with latest development version of GRUB 2. After that please send a patch to grub-devel for review. Please describe in your email why you made the change, what it changes and so on. Please be prepared to receive even discouraging comments about your patch. There is usually at least something that needs to be improved in every patch.

  Please use unified diff to make your patch (good match of arguments for diff is ‘-pruN’).

• Respond to received feedback.

  If you are asked to modify your patch, please do that and resubmit it for review. If your change is large you are required to submit a copyright agreement to FSF. Please keep in mind that if you are asked to submit for copyright agreement, process can take some time and is mandatory in order to get your changes integrated.

  If you are not on grub-devel to respond to questions, most likely your patch will not be accepted. Also if problems arise from your changes later on, it would be preferable that you also fix the problem. So stay around for a while.

• Your patch is accepted.

  Good job! Your patch will now be integrated into GRUB 2 mainline, and if it didn’t break anything it will be publicly available in the next release.

  Now you are welcome to do further improvements :)

4.2 Typical Developer Experience ¶

The typical experience for a developer in this project is the following:

1. You find yourself wanting to do something (e.g. fixing a bug).
2. You show some result in the mailing list or the IRC.
3. You are getting to be known to other developers.
4. You accumulate significant amount of contribution, so copyright assignment is processed.
5. You are free to check in your changes on your own, legally speaking.

At this point, it is rather annoying that you ought to ask somebody else every change to be checked in. For efficiency, it is far better, if you can commit it yourself. Therefore, our policy is to give you the write permission to our official repository, once you have shown your skill and will, and the FSF clerks have dealt with your copyright assignment.

4.3 When you are approved for write access to project’s files ¶

As you might know, GRUB is hosted on Savannah, thus the membership is managed by Savannah. This means that, if you want to be a member of this project:

1. You need to create your own account on Savannah.
2. You can submit “Request for Inclusion” from “My Groups” on Savannah.

Then, one of the admins can approve your request, and you will be a member. If you don’t want to use the Savannah interface to submit a request, you can simply notify the admins by email or something else, alternatively. But you still need to create an account beforehand.

NOTE: we sometimes receive a “Request for Inclusion” from an unknown person. In this case, the request would be just discarded, since it is too dangerous to allow a stranger to be a member, which automatically gives him a commit right to the repository, both for a legal reason and for a technical reason.

If your intention is to just get started, please do not submit a inclusion request. Instead, please subscribe to the mailing list, and communicate first (e.g. sending a patch, asking a question, commenting on another message...).

6.1 Gnulib ¶

Gnulib is a source code library that provides basic functionality to programs and libraries. Many software packages make use of Gnulib to avoid reinventing the portability wheel.

GRUB imports Gnulib using its bootstrap utility, identifying a particular Git commit in bootstrap.conf. To upgrade to a new Gnulib commit, set GNULIB_REVISION in bootstrap.conf to the new commit ID, then run ./bootstrap and whatever else you need to make sure it works. Check for changes to Gnulib’s NEWS file between the old and new commits; in some cases it will be necessary to adjust GRUB to match. You may also need to update the patches in grub-core/lib/gnulib-patches/.

To add a new Gnulib module or remove one that is no longer needed, change gnulib_modules in bootstrap.conf. Again, run ./bootstrap and whatever else you need to make sure it works.

Bootstrapping from an older distribution containing gettext version < 0.18.3, will require a patch similar to this to be applied first before running the ./bootstrap utility:

diff --git a/bootstrap.conf b/bootstrap.conf
index 988dda0..a3193a9 100644
--- a/bootstrap.conf
+++ b/bootstrap.conf
@ -67,7 +67,7 @ SKIP_PO=t
buildreq="\
autoconf   2.63
automake   1.11
-gettext    0.18.3
+gettext    0.17
git        1.5.5
tar        -
"
diff --git a/configure.ac b/configure.ac
index 08b518f..99f5b36 100644
--- a/configure.ac
+++ b/configure.ac
@ -362,7 +362,7 @ AC_CHECK_PROG(HAVE_CXX, $CXX, yes, no)

AC_GNU_SOURCE
AM_GNU_GETTEXT([external])
-AM_GNU_GETTEXT_VERSION([0.18.3])
+AM_GNU_GETTEXT_VERSION([0.17])
AC_SYS_LARGEFILE

# Identify characteristics of the host architecture.

It will also be necessary to adjust the patches in po/gettext-patches/ to apply to an older version of gettext.

6.2 jsmn ¶

jsmn is a minimalistic JSON parser which is implemented in a single header file jsmn.h. To import a different version of the jsmn parser, you may simply download the jsmn.h header from the desired tag or commit to the target directory:

curl -L https://raw.githubusercontent.com/zserge/jsmn/v1.1.0/jsmn.h \
    -o grub-core/lib/json/jsmn.h

6.3 minilzo ¶

miniLZO is a very lightweight subset of the LZO library intended for easy inclusion in other projects. It is generated automatically from the LZO source code and contains the most important LZO functions.

To upgrade to a new version of the miniLZO library, download the release tarball and copy the files into the target directory:

curl -L -O https://www.oberhumer.com/opensource/lzo/download/minilzo-2.10.tar.gz
tar -zxf minilzo-2.10.tar.gz
rm minilzo-2.10/testmini.c
rm -r grub-core/lib/minilzo/*
cp minilzo-2.10/*.[hc] grub-core/lib/minilzo
rm -r minilzo-2.10*

7.1 i386-pc ¶

The i386-pc target is a good place to start when first debugging GRUB2 because in some respects it’s easier than EFI platforms. The reason being that the initial load address is always known in advance. To start debugging GRUB2 first QEMU must be started in GDB stub mode. The following command is a simple illustration:

qemu-system-i386 -drive file=disk.img,format=raw \
    -device virtio-scsi-pci,id=scsi0 -S -s

This will start a QEMU instance booting from disk.img. It will pause at start waiting for a GDB instance to attach to it. You should change disk.img to something more appropriate. A block device can be used, but you may need to run QEMU as a privileged user.

To connect to this QEMU instance with GDB, the target remote GDB command must be used. We also need to load a binary image, preferably with symbols. This can be done using the GDB command file kernel.exec, if GDB is started from the grub-core directory in the GRUB2 build directory. GRUB2 developers have made this more simple by including a GDB script which does much of the setup. This file is at grub-core/gdb_grub in the build directory and is also installed via make install. When using a pre-built GRUB, the distribution may have a package which installs this GDB script along with debug symbol binaries, such as Debian’s ‘grub-pc-dbg’ package. The GDB script is intended to be used like so, assuming that ‘/path/to/script’ is the path to the directory containing the gdb_grub script and debug symbol files:

cd $(dirname /path/to/script/gdb_grub)
gdb -x gdb_grub

Once GDB has been started with the gdb_grub script it will automatically connect to the QEMU instance. You can then do things you normally would in GDB like set a break point on grub_main.

Setting breakpoints in modules is trickier since they haven’t been loaded yet and are loaded at addresses determined at runtime. The module could be loaded to different addresses in different QEMU instances. The debug symbols in the modules .module binary, thus are always wrong, and GDB needs to be told where to load the symbols to. But this must happen at runtime after GRUB2 has determined where the module will get loaded. Luckily the gdb_grub script takes care of this with the runtime_load_module command, which configures GDB to watch for GRUB2 module loading and when it does add the module symbols with the appropriate offset.

7.2 x86_64-efi ¶

Using GDB to debug GRUB2 for the x86_64-efi target has some similarities with the i386-pc target. Please read and familiarize yourself with the i386-pc section when reading this one. Extra care must be used to run QEMU such that it boots a UEFI firmware. This usually involves either using the ‘-bios’ option with a UEFI firmware blob (eg. OVMF.fd) or loading the firmware via pflash. This document will not go further into how to do this as there are ample resource on the web.

Like all EFI implementations, on x86_64-efi the (U)EFI firmware that loads the GRUB2 EFI application determines at runtime where the application will be loaded. This means that we do not know where to tell GDB to load the symbols for the GRUB2 core until the (U)EFI firmware determines it. There are two good ways of figuring this out when running in QEMU: use a debug build of OVMF and check the debug log, or have GRUB2 say where it is loaded. Neither of these are ideal because they both generally give the information after GRUB2 is already running, which makes debugging early boot infeasible. Technically, the first method does give the load address before GRUB2 is run, but without debugging the EFI firmware with symbols, the author currently does not know how to cause the OVMF firmware to pause at that point to use the load address before GRUB2 is run.

Even after getting the application load address, the loading of core symbols is complicated by the fact that the debugging symbols for the kernel are in an ELF binary named kernel.exec while what is in memory are sections for the PE32+ EFI binary. When grub-mkimage creates the PE32+ binary it condenses several segments from the ELF kernel binary into one .data section in the PE32+ binary. This must be taken into account to properly load the other non-text sections. Otherwise, GDB will work as expected when breaking on functions, but, for instance, global variables will point to the wrong address in memory and thus give incorrect values (which can be difficult to debug).

Calculating the correct offsets for sections is taken care of automatically when loading the kernel symbols via the user-defined GDB command dynamic_load_kernel_exec_symbols, which takes one argument, the address where the text section is loaded as determined by one of the methods above. Alternatively, the command dynamic_load_symbols with the text section address as an agrument can be called to load the kernel symbols and set up loading the module symbols as they are loaded at runtime.

In the author’s experience, when debugging with QEMU and OVMF, to have debugging symbols loaded at the start of GRUB2 execution the GRUB2 EFI application must be run via QEMU at least once prior in order to get the load address. Two methods for obtaining the load address are described in two subsections below. Generally speaking, the load address does not change between QEMU runs. There are exceptions to this, namely that different GRUB2 EFI applications can be run at different addresses. Also, it has been observed that after running the EFI application for the first time, the second run will sometimes have a different load address, but subsequent runs of the same EFI application will have the same load address as the second run. And it’s a near certainty that if the GRUB EFI binary has changed, eg. been recompiled, the load address will also be different.

This ability to predict what the load address will be allows one to assume the load address on subsequent runs and thus load the symbols before GRUB2 starts. The following command illustrates this, assuming that QEMU is running and waiting for a debugger connection and the current working directory is where gdb_grub resides:

gdb -x gdb_grub -ex 'dynamic_load_symbols address of .text section'

If you load the symbols in this manner and, after continuing execution, do not see output showing the module symbols loading, then it is very likely that the load address was incorrect.

Another thing to be aware of is how the loading of the GRUB image by the firmware affects previously set software breakpoints. On x86 platforms, software breakpoints are implemented by GDB by writing a special processor instruction at the location of the desired breakpoint. This special instruction when executed will stop the program execution and hand control to the debugger, GDB. GDB will first save the instruction bytes that are overwritten at the breakpoint and will put them back when the breakpoint is hit. If GRUB is being run for the first time in QEMU, the firmware will be loading the GRUB image into memory where every byte is already set to 0. This means that if a breakpoint is set before GRUB is loaded, GDB will save the 0-byte(s) where the the special instruction will go. Then when the firmware loads the GRUB image and because it is unaware of the debugger, it will write the GRUB image to memory, overwriting anything that was there previously — notably in this case the instruction that implements the software breakpoint. This will be confusing for the person using GDB because GDB will show the breakpoint as set, but the brekapoint will never be hit. Furthermore, GDB then becomes confused, such that even deleting an recreating the breakpoint will not create usable breakpoints. The gdb_grub script takes care of this by saving the breakpoints just before they are overwritten, and then restores them at the start of GRUB execution. So breakpoints for GRUB can be set before GRUB is loaded, but be mindful of this effect if you are confused as to why breakpoints are not getting hit.

Also note, that hardware breakpoints do not suffer this problem. They are implemented by having the breakpoint address in special debug registers on the CPU. So they can always be set freely without regard to whether GRUB has been loaded or not. The reason that hardware breakpoints aren’t always used is because there are a limited number of them, usually around 4 on various CPUs, and specifically exactly 4 for x86 CPUs. The gdb_grub script goes out of its way to avoid using hardware breakpoints internally and uses them as briefly as possible when needed, thus allowing the user to have a maximal number at their disposal.

• OVMF debug log
• Using the gdbinfo command

qemu-system-x86_64 -bios /path/to/debug/OVMF.fd \
    -drive file=disk.img,format=raw \
    -device virtio-scsi-pci,id=scsi0 \
    -debugcon file:debug.log -global isa-debugcon.iobase=0x402

12.1 Video API ¶

• grub_video_setup
• grub_video_restore
• grub_video_get_info
• grub_video_get_blit_format
• grub_video_set_palette
• grub_video_get_palette
• grub_video_set_area_status
• grub_video_get_area_status
• grub_video_set_viewport
• grub_video_get_viewport
• grub_video_set_region
• grub_video_get_region
• grub_video_map_color
• grub_video_map_rgb
• grub_video_map_rgba
• grub_video_unmap_color
• grub_video_fill_rect
• grub_video_blit_glyph
• grub_video_blit_bitmap
• grub_video_blit_render_target
• grub_video_scroll
• grub_video_swap_buffers
• grub_video_create_render_target
• grub_video_delete_render_target
• grub_video_set_active_render_target
• grub_video_get_active_render_target

12.2 Example usage of Video API ¶

• Example of screen setup
• Example of setting up console viewport

grub_err_t rc;
/* Try to initialize video mode 1024 x 768 with direct RGB.  */
rc = grub_video_setup (1024, 768, GRUB_VIDEO_MODE_TYPE_RGB);
if (rc != GRUB_ERR_NONE)
{
  /* Fall back to standard VGA Index Color mode.  */
  rc = grub_video_setup (640, 480, GRUB_VIDEO_MODE_TYPE_INDEX);
  if (rc != GRUB_ERR_NONE)
  {
  /* Handle error.  */
  }
}

grub_uint32_t x, y, width, height;
grub_video_color_t color;
struct grub_font_glyph glyph;
grub_err_t rc;
/* Query existing viewport.  */
grub_video_get_viewport (&x, &y, &width, &height);
/* Fill background.  */
color = grub_video_map_color (GRUB_COLOR_BACKGROUND);
grub_video_fill_rect (color, 0, 0, width, height);
/* Setup console viewport.  */
grub_video_set_viewport (x + 10, y + 10, width - 20, height - 20);
grub_video_get_viewport (&x, &y, &width, &height);
color = grub_video_map_color (GRUB_COLOR_CONSOLE_BACKGROUND);
grub_video_fill_rect (color, 0, 0, width, height);
/* Draw text to viewport.  */
color = grub_video_map_color (GRUB_COLOR_CONSOLE_TEXT);
grub_font_get_glyph ('X', &glyph);
grub_video_blit_glyph (&glyph, color, 0, 0);

12.3 Bitmap API ¶

• grub_video_bitmap_create
• grub_video_bitmap_destroy
• grub_video_bitmap_load
• grub_video_bitmap_get_width
• grub_video_bitmap_get_height
• grub_video_bitmap_get_mode_info
• grub_video_bitmap_get_data

13.1 Introduction ¶

The goal of this format is to provide a bitmap font format that is simple to use, compact, and cleanly supports Unicode.

• Goals of the GRUB Font Format
• Why Another Font Format?

13.2 File Structure ¶

A file section consists of a 4-byte name, a 32-bit big-endian length (not including the name or length), and then length more section-type-specific bytes.

The standard file extension for PFF2 font files is .pf2.

• Section Types

13.3 Font Metrics ¶

• Ascent. The distance from the baseline to the top of most characters. Note that in some cases characters may extend above the ascent.
• Descent. The distance from the baseline to the bottom of most characters. Note that in some cases characters may extend below the descent.
• Leading. The amount of space, in pixels, to leave between the descent of one line of text and the ascent of the next line. This metrics is not specified in the current file format; instead, the font rendering engine calculates a reasonable leading value based on the other font metrics.
• Horizonal leading. The amount of space, in pixels, to leave horizontally between the left and right edges of two adjacent glyphs. The device width field determines the effective leading value that is used to render the font.

An illustration of how the various font metrics apply to characters.

14.1 Introduction ¶

The ‘gfxmenu’ module provides a graphical menu interface for GRUB 2. It functions as an alternative to the menu interface provided by the ‘normal’ module, which uses the grub terminal interface to display a menu on a character-oriented terminal.

The graphical menu uses the GRUB video API, which is currently for the VESA BIOS extensions (VBE) 2.0+. This is supported on the i386-pc platform. However, the graphical menu itself does not depend on using VBE, so if another GRUB video driver were implemented, the ‘gfxmenu’ graphical menu would work on the new video driver as well.

14.2 Startup Sequence ¶

• grub_enter_normal_mode [normal/main.c]
• grub_normal_execute [normal/main.c]
• read_config_file [normal/main.c]
• (When gfxmenu.mod is loaded with insmod, it will call grub_menu_viewer_register() to register itself.)
• GRUB_MOD_INIT (gfxmenu) [gfxmenu/gfxmenu.c]
• grub_menu_viewer_register [kern/menu_viewer.c]
• grub_menu_viewer_show_menu [kern/menu_viewer.c]
• get_current_menu_viewer() [kern/menu_viewer.c]
• show_menu() [gfxmenu/gfxmenu.c]
• grub_gfxmenu_model_new [gfxmenu/model.c]
• grub_gfxmenu_view_new [gfxmenu/view.c]
• set_graphics_mode [gfxmenu/view.c]
• grub_gfxmenu_view_load_theme [gfxmenu/theme_loader.c]

14.3 GUI Components ¶

The graphical menu implements a GUI component system that supports a container-based layout system. Components can be added to containers, and containers (which are a type of component) can then be added to other containers, to form a tree of components. Currently, the root component of this tree is a ‘canvas’ component, which allows manual layout of its child components.

Components (non-container):

• label
• image
• progress_bar
• circular_progress
• list (currently hard coded to be a boot menu list)

Containers:

• canvas
• hbox
• vbox

The GUI component instances are created by the theme loader in gfxmenu/theme_loader.c when a theme is loaded. Theme files specify statements such as ‘+vbox{ +label { text="Hello" } +label{ text="World" } }’ to add components to the component tree root. By nesting the component creation statements in the theme file, the instantiated components are nested the same way.

When a component is added to a container, that new child is considered owned by the container. Great care should be taken if the caller retains a reference to the child component, since it will be destroyed if its parent container is destroyed. A better choice instead of storing a pointer to the child component is to use the component ID to find the desired component. Component IDs do not have to be unique (it is often useful to have multiple components with an ID of "__timeout__", for instance).

In order to access and use components in the component tree, there are two functions (defined in gfxmenu/gui_util.c) that are particularly useful:

• grub_gui_find_by_id (root, id, callback, userdata):

  This function recursively traverses the component tree rooted at root, and for every component that has an ID equal to id, calls the function pointed to by callback with the matching component and the void pointer userdata as arguments. The callback function can do whatever is desired to use the component passed in.

• grub_gui_iterate_recursively (root, callback, userdata):

  This function calls the function pointed to by callback for every component that is a descendant of root in the component tree. When the callback function is called, the component and the void pointer userdata as arguments. The callback function can do whatever is desired to use the component passed in.

14.4 Command Line Window ¶

The terminal window used to provide command line access within the graphical menu is managed by gfxmenu/view.c. The ‘gfxterm’ terminal is used, and it has been modified to allow rendering to an offscreen render target to allow it to be composed into the double buffering system that the graphical menu view uses. This is bad for performance, however, so it would probably be a good idea to make it possible to temporarily disable double buffering as long as the terminal window is visible. There are still unresolved problems that occur when commands are executed from the terminal window that change the graphics mode. It’s possible that making grub_video_restore() return to the graphics mode that was in use before grub_video_setup() was called might fix some of the problems.