1 This is /home/phcoder/grub2/bzr/mainline/docs/grub-dev.info, produced
2 by makeinfo version 4.13 from
3 /home/phcoder/grub2/bzr/mainline/docs/grub-dev.texi.
5 This developer manual is for GNU GRUB (version 2.00, 22 May 2012).
7 Copyright (C) 1999,2000,2001,2002,2004,2005,2006,2008,2009,2010,2011
8 Free Software Foundation, Inc.
10 Permission is granted to copy, distribute and/or modify this
11 document under the terms of the GNU Free Documentation License,
12 Version 1.2 or any later version published by the Free Software
13 Foundation; with no Invariant Sections.
15 INFO-DIR-SECTION Kernel
17 * grub-dev: (grub-dev). The GRand Unified Bootloader Dev
21 File: grub-dev.info, Node: Top, Next: Getting the source code, Up: (dir)
23 GNU GRUB developer manual
24 *************************
26 This is the developer documentation of GNU GRUB, the GRand Unified
27 Bootloader, a flexible and powerful boot loader program for a wide
28 range of architectures.
30 This edition documents version 2.00.
32 This developer manual is for GNU GRUB (version 2.00, 22 May 2012).
34 Copyright (C) 1999,2000,2001,2002,2004,2005,2006,2008,2009,2010,2011
35 Free Software Foundation, Inc.
37 Permission is granted to copy, distribute and/or modify this
38 document under the terms of the GNU Free Documentation License,
39 Version 1.2 or any later version published by the Free Software
40 Foundation; with no Invariant Sections.
44 * Getting the source code::
45 * Finding your way around::
47 * Contributing Changes::
51 * BIOS port memory map::
53 * PFF2 Font File Format::
54 * Graphical Menu Software Design::
55 * Copying This Manual:: Copying This Manual
59 File: grub-dev.info, Node: Getting the source code, Next: Finding your way around, Prev: Top, Up: Top
61 1 Getting the source code
62 *************************
64 GRUB is maintained using the Bazaar revision control system
65 (http://bazaar-vcs.org/). To fetch the primary development branch:
67 bzr get http://bzr.savannah.gnu.org/r/grub/trunk/grub
69 The GRUB developers maintain several other branches with work in
70 progress. Of these, the most interesting is the experimental branch,
71 which is a staging area for new code which we expect to eventually
72 merge into trunk but which is not yet ready:
74 bzr get http://bzr.savannah.gnu.org/r/grub/branches/experimental
76 Once you have used `bzr get' to fetch an initial copy of a branch,
77 you can use `bzr pull' to keep it up to date. If you have modified your
78 local version, you may need to resolve conflicts when pulling.
81 File: grub-dev.info, Node: Coding style, Next: Contributing Changes, Prev: Finding your way around, Up: Top
86 Basically we follow the GNU Coding Standards
87 (http://www.gnu.org/prep/standards_toc.html). We define additional
88 conventions for GRUB here.
92 * Naming Conventions::
98 * Multi-Line Comments::
101 File: grub-dev.info, Node: Naming Conventions, Next: Functions, Up: Coding style
103 2.1 Naming Conventions
104 ======================
106 All global symbols (i.e. functions, variables, types, and macros) must
107 have the prefix grub_ or GRUB_. The all capital form is used only by
111 File: grub-dev.info, Node: Functions, Next: Variables, Prev: Naming Conventions, Up: Coding style
116 If a function is global, its name must be prefixed with grub_ and must
117 consist of only small letters. If the function belongs to a specific
118 function module, the name must also be prefixed with the module name.
119 For example, if a function is for file systems, its name is prefixed
120 with grub_fs_. If a function is for FAT file system but not for all
121 file systems, its name is prefixed with grub_fs_fat_. The hierarchy is
124 After a prefix, a function name must start with a verb (such as get
125 or is). It must not be a noun. Some kind of abbreviation is permitted,
126 as long as it wouldn't make code less readable (e.g. init).
128 If a function is local, its name may not start with any prefix. It
129 must start with a verb.
132 File: grub-dev.info, Node: Variables, Next: Types, Prev: Functions, Up: Coding style
137 The rule is mostly the same as functions, as noted above. If a variable
138 is global, its name must be prefixed with grub_ and must consist of
139 only small letters. If the variable belongs to a specific function
140 module, the name must also be prefixed with the module name. For
141 example, if a function is for dynamic loading, its name is prefixed
142 with grub_dl_. If a variable is for ELF but not for all dynamic loading
143 systems, its name is prefixed with grub_dl_elf_.
145 After a prefix, a variable name must start with a noun or an
146 adjective (such as name or long) and it should end with a noun. Some
147 kind of abbreviation is permitted, as long as it wouldn't make code
148 less readable (e.g. i18n).
150 If a variable is global in the scope of a single file (i.e. it is
151 declared with static), its name may not start with any prefix. It must
152 start with a noun or an adjective.
154 If a variable is local, you may choose any shorter name, as long as
155 it wouldn't make code less readable (e.g. i).
158 File: grub-dev.info, Node: Types, Next: Macros, Prev: Variables, Up: Coding style
163 The name of a type must be prefixed with grub_ and must consist of only
164 small letters. If the type belongs to a specific function module, the
165 name must also be prefixed with the module name. For example, if a type
166 is for OS loaders, its name is prefixed with grub_loader_. If a type is
167 for Multiboot but not for all OS loaders, its name is prefixed with
170 The name must be suffixed with _t, to emphasize the fact that it is
171 a type but not a variable or a function.
174 File: grub-dev.info, Node: Macros, Next: Comments, Prev: Types, Up: Coding style
179 If a macro is global, its name must be prefixed with GRUB_ and must
180 consist of only large letters. Other rules are the same as functions or
181 variables, depending on whether a macro is used like a function or a
185 File: grub-dev.info, Node: Comments, Next: Multi-Line Comments, Prev: Macros, Up: Coding style
190 All comments shall be C-style comments, of the form `/* ... */'.
192 Comments shall be placed only on a line by themselves. They shall
193 not be placed together with code, variable declarations, or other
194 non-comment entities. A comment should be placed immediately preceding
195 the entity it describes.
198 /* The page # that is the front buffer. */
200 /* The page # that is the back buffer. */
204 int displayed_page; /* The page # that is the front buffer. */
205 int render_page; /* The page # that is the back buffer. */
208 File: grub-dev.info, Node: Multi-Line Comments, Prev: Comments, Up: Coding style
210 2.7 Multi-Line Comments
211 =======================
213 Comments spanning multiple lines shall be formatted with all lines
214 after the first aligned with the first line.
216 Asterisk characters should not be repeated a the start of each
221 which spans multiple lines.
227 * which spans multiple lines.
230 The opening `/*' and closing `*/' should be placed together on a
234 File: grub-dev.info, Node: Finding your way around, Next: Coding style, Prev: Getting the source code, Up: Top
236 3 Finding your way around
237 *************************
239 Here is a brief map of the GRUB code base.
241 GRUB uses Autoconf and Automake, with most of the Automake input
242 generated by AutoGen. The top-level build rules are in `configure.ac',
243 `grub-core/Makefile.core.def', and `Makefile.util.def'. Each block in
244 a `*.def' file represents a build target, and specifies the source
245 files used to build it on various platforms. The `*.def' files are
246 processed into AutoGen input by `gentpl.py' (which you only need to
247 look at if you are extending the build system). If you are adding a new
248 module which follows an existing pattern, such as a new command or a new
249 filesystem implementation, it is usually easiest to grep
250 `grub-core/Makefile.core.def' and `Makefile.util.def' for an existing
251 example of that pattern to find out where it should be added.
253 In general, code that may be run at boot time is in a subdirectory of
254 `grub-core', while code that is only run from within a full operating
255 system is in a subdirectory of the top level.
257 Low-level boot code, such as the MBR implementation on PC BIOS
258 systems, is in the `grub-core/boot/' directory.
260 The GRUB kernel is in `grub-core/kern/'. This contains core
261 facilities such as the device, disk, and file frameworks, environment
262 variable handling, list processing, and so on. The kernel should
263 contain enough to get up to a rescue prompt. Header files for kernel
264 facilities, among others, are in `include/'.
266 Terminal implementations are in `grub-core/term/'.
268 Disk access code is spread across `grub-core/disk/' (for accessing
269 the disk devices themselves), `grub-core/partmap/' (for interpreting
270 partition table data), and `grub-core/fs/' (for accessing filesystems).
271 Note that, with the odd specialised exception, GRUB only contains code
272 to _read_ from filesystems and tries to avoid containing any code to
273 _write_ to filesystems; this lets us confidently assure users that GRUB
274 cannot be responsible for filesystem corruption.
276 PCI and USB bus handling is in `grub-core/bus/'.
278 Video handling code is in `grub-core/video/'. The graphical menu
279 system uses this heavily, but is in a separate directory,
280 `grub-core/gfxmenu/'.
282 Most commands are implemented by files in `grub-core/commands/', with
283 the following exceptions:
285 * A few core commands live in `grub-core/kern/corecmd.c'.
287 * Commands related to normal mode live under `grub-core/normal/'.
289 * Commands that load and boot kernels live under `grub-core/loader/'.
291 * The `loopback' command is really a disk device, and so lives in
292 `grub-core/disk/loopback.c'.
294 * The `gettext' command lives under `grub-core/gettext/'.
296 * The `loadfont' and `lsfonts' commands live under `grub-core/font/'.
298 * The `serial', `terminfo', and `background_image' commands live
299 under `grub-core/term/'.
301 * The `efiemu_*' commands live under `grub-core/efiemu/'.
303 There are a few other special-purpose exceptions; grep for them if
306 Utility programs meant to be run from a full operating system are in
310 File: grub-dev.info, Node: Contributing Changes, Next: Porting, Prev: Coding style, Up: Top
312 4 Contributing changes
313 **********************
315 Contributing changes to GRUB 2 is welcomed activity. However we have a
316 bit of control what kind of changes will be accepted to GRUB 2.
317 Therefore it is important to discuss your changes on grub-devel mailing
318 list (see MailingLists). On this page there are some basic details on
319 the development process and activities.
321 First of all you should come up with the idea yourself what you want
322 to contribute. If you do not have that beforehand you are advised to
323 study this manual and try GRUB 2 out to see what you think is missing
326 Here are additional pointers:
327 * `https://savannah.gnu.org/task/?group=grub GRUB's Task Tracker'
329 * `https://savannah.gnu.org/bugs/?group=grub GRUB's Bug Tracker'
331 If you intended to make changes to GRUB Legacy (<=0.97) those are
332 not accepted anymore.
337 * Typical Developer Experience::
338 * When you are approved for write access to project's files::
341 File: grub-dev.info, Node: Getting started, Next: Typical Developer Experience, Up: Contributing Changes
346 * Always use latest GRUB 2 source code. So get that first.
348 For developers it is recommended always to use the newest
349 development version of GRUB 2. If development takes a long period
350 of time, please remember to keep in sync with newest developments
351 regularly so it is much easier to integrate your change in the
352 future. GRUB 2 is being developed in a Bazaar (bzr) repository.
354 Please check Savannah's GRUB project page for details how to get
355 newest bzr: GRUB 2 bzr Repository
356 (http://savannah.gnu.org/bzr/?group=grub)
358 * Compile it and try it out.
360 It is always good idea to first see that things work somehow and
361 after that to start to implement new features or develop fixes to
366 There are sometimes odd ways to do things in GRUB 2 code base.
367 This is mainly related to limited environment where GRUB 2 is
368 being executed. You usually do not need to understand it all so
369 it is better to only try to look at places that relates to your
370 work. Please do not hesitate to ask for help if there is something
371 that you do not understand.
373 * Develop a new feature.
375 Now that you know what to do and how it should work in GRUB 2 code
376 base, please be free to develop it. If you have not so far
377 announced your idea on grub-devel mailing list, please do it now.
378 This is to make sure you are not wasting your time working on the
379 solution that will not be integrated to GRUB 2 code base.
381 You might want to study our coding style before starting
382 development so you do not need to change much of the code when
383 your patch is being reviewed. (see *note Coding style::)
385 For every accepted patch there has to exist a ChangeLog entry. Our
386 ChangeLog consist of changes within source code and are not
387 describing about what the change logically does. Please see
388 examples from previous entries.
390 Also remember that GRUB 2 is licensed under GPLv3 license and that
391 usually means that you are not allowed to copy pieces of code from
392 other projects. Even if the source project's license would be
393 compatible with GPLv3, please discuss it beforehand on grub-devel
398 Test that your change works properly. Try it out a couple of
399 times, preferably on different systems, and try to find problems
402 * Publish your change.
404 When you are happy with your change, first make sure it is
405 compilable with latest development version of GRUB 2. After that
406 please send a patch to grub-devel for review. Please describe in
407 your email why you made the change, what it changes and so on.
408 Please be prepared to receive even discouraging comments about
409 your patch. There is usually at least something that needs to be
410 improved in every patch.
412 Please use unified diff to make your patch (good match of
413 arguments for diff is `-pruN').
415 * Respond to received feedback.
417 If you are asked to modify your patch, please do that and resubmit
418 it for review. If your change is large you are required to submit
419 a copyright agreement to FSF. Please keep in mind that if you are
420 asked to submit for copyright agreement, process can take some
421 time and is mandatory in order to get your changes integrated.
423 If you are not on grub-devel to respond to questions, most likely
424 your patch will not be accepted. Also if problems arise from your
425 changes later on, it would be preferable that you also fix the
426 problem. So stay around for a while.
428 * Your patch is accepted.
430 Good job! Your patch will now be integrated into GRUB 2 mainline,
431 and if it didn't break anything it will be publicly available in
434 Now you are welcome to do further improvements :)
437 File: grub-dev.info, Node: Typical Developer Experience, Next: When you are approved for write access to project's files, Prev: Getting started, Up: Contributing Changes
439 4.2 Typical Developer Experience
440 ================================
442 The typical experience for a developer in this project is the following:
444 1. You find yourself wanting to do something (e.g. fixing a bug).
446 2. You show some result in the mailing list or the IRC.
448 3. You are getting to be known to other developers.
450 4. You accumulate significant amount of contribution, so copyright
451 assignment is processed.
453 5. You are free to check in your changes on your own, legally
456 At this point, it is rather annoying that you ought to ask somebody
457 else every change to be checked in. For efficiency, it is far better,
458 if you can commit it yourself. Therefore, our policy is to give you the
459 write permission to our official repository, once you have shown your
460 skill and will, and the FSF clerks have dealt with your copyright
464 File: grub-dev.info, Node: When you are approved for write access to project's files, Prev: Typical Developer Experience, Up: Contributing Changes
466 4.3 When you are approved for write access to project's files
467 =============================================================
469 As you might know, GRUB is hosted on
470 `https://savannah.gnu.org/projects/grub Savannah', thus the membership
471 is managed by Savannah. This means that, if you want to be a member of
474 1. You need to create your own account on Savannah.
476 2. You can submit "Request for Inclusion" from "My Groups" on
479 Then, one of the admins can approve your request, and you will be a
480 member. If you don't want to use the Savannah interface to submit a
481 request, you can simply notify the admins by email or something else,
482 alternatively. But you still need to create an account beforehand.
484 NOTE: we sometimes receive a "Request for Inclusion" from an unknown
485 person. In this case, the request would be just discarded, since it is
486 too dangerous to allow a stranger to be a member, which automatically
487 gives him a commit right to the repository, both for a legal reason and
488 for a technical reason.
490 If your intention is to just get started, please do not submit a
491 inclusion request. Instead, please subscribe to the mailing list, and
492 communicate first (e.g. sending a patch, asking a question, commenting
493 on another message...).
496 File: grub-dev.info, Node: Porting, Next: Error Handling, Prev: Contributing Changes, Up: Top
501 GRUB2 is designed to be easily portable accross platforms. But because
502 of the nature of bootloader every new port must be done separately.
503 Here is how I did MIPS (loongson and ARC) and Xen ports. Note than this
504 is more of suggestions, not absolute truth.
506 First of all grab any architecture specifications you can find in
507 public (please avoid NDA).
509 First stage is "Hello world". I've done it outside of GRUB for
510 simplicity. Your task is to have a small program which is loadable as
511 bootloader and clearly shows its presence to you. If you have easily
512 accessible console you can just print a message. If you have a mapped
513 framebuffer you know address of, you can draw a square. If you have a
514 debug facility, just hanging without crashing might be enough. For the
515 first stage you can choose to load the bootloader across the network
516 since format for network image is often easier than for local boot and
517 it skips the need of small intermediary stages and nvram handling.
518 Additionally you can often have a good idea of the needed format by
519 running "file" on any netbootable executable for given platform.
521 This program should probably have 2 parts: an assembler and C one.
522 Assembler one handles BSS cleaning and other needed setup (on some
523 platforms you may need to switch modes or copy the executable to its
524 definitive position). So your code may look like (x86 assembly for
525 illustration purposes)
529 movl $_bss_start, %edi
539 static const char msg[] = "Hello, world";
550 const char *ptr = msg;
556 Sometimes you need a third file: assembly stubs for
559 Once this file is functional it's time to move it into GRUB2. The
560 startup assembly file goes to grub-core/kern/$cpu/$platform/startup.S.
561 You should also include grub/symbol.h and replace call to entry point
562 with call to EXT_C(grub_main). The C file goes to
563 grub-core/kern/$cpu/$platform/init.c and its entry point is renamed to
564 void grub_machine_init (void). Keep final infinite loop for now. Stubs
565 file if any goes to grub-core/kern/$cpu/$platform/callwrap.S. Sometimes
566 either $cpu or $platform is dropped if file is used on several cpus
567 respectivelyplatforms. Check those locations if they already have what
570 Then modify in configure.ac the following parts:
574 case "$target_cpu" in
575 i[[3456]]86) target_cpu=i386 ;;
576 amd64) target_cpu=x86_64 ;;
577 sparc) target_cpu=sparc64 ;;
578 s390x) target_cpu=s390 ;;
582 Sometimes CPU have additional architecture names which don't
583 influence booting. You might want to have some canonical name to avoid
584 having bunch of identical platforms with different names.
586 NOTE: it doesn't influence compile optimisations which depend solely
587 on chosen compiler and compile options.
589 if test "x$with_platform" = x; then
590 case "$target_cpu"-"$target_vendor" in
591 i386-apple) platform=efi ;;
592 i386-*) platform=pc ;;
593 x86_64-apple) platform=efi ;;
594 x86_64-*) platform=pc ;;
595 powerpc-*) platform=ieee1275 ;;
602 This part deals with guessing the platform from CPU and vendor.
603 Sometimes you need to use 32-bit mode for booting even if OS runs in
604 64-bit one. If so add your platform to:
606 case "$target_cpu"-"$platform" in
609 x86_64-*) target_cpu=i386 ;;
610 powerpc64-ieee1275) target_cpu=powerpc ;;
613 Add your platform to the list of supported ones:
615 case "$target_cpu"-"$platform" in
624 If explicit -m32 or -m64 is needed add it to:
626 case "$target_cpu" in
627 i386 | powerpc) target_m32=1 ;;
628 x86_64 | sparc64) target_m64=1 ;;
631 Finally you need to add a conditional to the following block:
633 AM_CONDITIONAL([COND_mips_arc], [test x$target_cpu = xmips -a x$platform = xarc])
634 AM_CONDITIONAL([COND_sparc64_ieee1275], [test x$target_cpu = xsparc64 -a x$platform = xieee1275])
635 AM_CONDITIONAL([COND_powerpc_ieee1275], [test x$target_cpu = xpowerpc -a x$platform = xieee1275])
637 Next stop is gentpl.py. You need to add your platform to the list of
638 supported ones (sorry that this list is duplicated):
640 GRUB_PLATFORMS = [ "emu", "i386_pc", "i386_efi", "i386_qemu", "i386_coreboot",
641 "i386_multiboot", "i386_ieee1275", "x86_64_efi",
642 "mips_loongson", "sparc64_ieee1275",
643 "powerpc_ieee1275", "mips_arc", "ia64_efi",
644 "mips_qemu_mips", "s390_mainframe" ]
646 You may also want already to add new platform to one or several of
647 available groups. In particular we always have a group for each CPU
648 even when only one platform for given CPU is available.
650 Then comes grub-core/Makefile.core.def. In the block "kernel" you'll
651 need to define ldflags for your platform ($cpu_$platform_ldflags). You
652 also need to declare startup asm file ($cpu_$platform_startup) as well
653 as any other files (e.g. init.c and callwrap.S) (e.g. $cpu_$platform =
654 kern/$cpu/$platform/init.c). At this stage you will also need to add
655 dummy dl.c and cache.S with functions grub_err_t
656 grub_arch_dl_check_header (void *ehdr), grub_err_t
657 grub_arch_dl_relocate_symbols (grub_dl_t mod, void *ehdr) (dl.c) and
658 void grub_arch_sync_caches (void *address, grub_size_t len) (cache.S).
659 They won't be used for now.
661 You will need to create directory include/$cpu/$platform and a file
662 include/$cpu/types.h. The later folowing this template:
664 #ifndef GRUB_TYPES_CPU_HEADER
665 #define GRUB_TYPES_CPU_HEADER 1
667 /* The size of void *. */
668 #define GRUB_TARGET_SIZEOF_VOID_P 4
670 /* The size of long. */
671 #define GRUB_TARGET_SIZEOF_LONG 4
673 /* mycpu is big-endian. */
674 #define GRUB_TARGET_WORDS_BIGENDIAN 1
675 /* Alternatively: mycpu is little-endian. */
676 #undef GRUB_TARGET_WORDS_BIGENDIAN
678 #endif /* ! GRUB_TYPES_CPU_HEADER */
680 You will also need to add a dummy file to datetime and setjmp
681 modules to avoid any of it having no files. It can be just completely
684 You'll need to make grub-mkimage.c (util/grub_mkimage.c) aware of
685 the needed format. For most commonly used formats like ELF, PE, aout or
686 raw the support is already present and you'll need to make it follow
687 the existant code paths for your platform adding adjustments if
688 necessary. When done compile:
691 ./configure --target=$cpu --with-platform=$platform TARGET_CC=.. OBJCOPY=... STRIP=...
696 ./grub-mkimage -d grub-core -O $format_id -o test.img
698 And it's time to test your test.img.
700 If it works next stage is to have heap, console and timer.
702 To have the heap working you need to determine which regions are
703 suitable for heap usage, allocate them from firmware and map (if
704 applicable). Then call grub_mm_init_region (vois *start, grub_size_t s)
705 for every of this region. As a shortcut for early port you can
706 allocate right after _end or have a big static array for heap. If you
707 do you'll probably need to come back to this later. As for output
708 console you should distinguish between an array of text, terminfo or
709 graphics-based console. Many of real-world examples don't fit perfectly
710 into any of these categories but one of the models is easier to be used
711 as base. In second and third case you should add your platform to
712 terminfokernel respectively videoinkernel group. A good example of
713 array of text is i386-pc (kern/i386/pc/init.c and
714 term/i386/pc/console.c). Of terminfo is ieee1275 (kern/ieee1275/init.c
715 and term/ieee1275/console.c). Of video is loongson
716 (kern/mips/loongson/init.c). Note that terminfo has to be inited in 2
717 stages: one before (to get at least rudimentary console as early as
718 possible) and another after the heap (to get full-featured console).
719 For the input there are string of keys, terminfo and direct hardware.
720 For string of keys look at i386-pc (same files), for termino ieee1275
721 (same files) and for hardware loongson (kern/mips/loongson/init.c and
724 For the timer you'll need to call grub_install_get_time_ms (...)
725 with as sole argument a function returning a grub_uint64_t of a number
726 of milliseconds elapsed since arbitrary point in the past.
728 Once these steps accomplished you can remove the inifinite loop and
729 you should be able to get to the minimal console. Next step is to have
730 module loading working. For this you'll need to fill kern/$cpu/dl.c and
731 kern/$cpu/cache.S with real handling of relocations and respectively
732 the real sync of I and D caches. Also you'll need to decide where in
733 the image to store the modules. Usual way is to have it concatenated
734 at the end. In this case you'll need to modify startup.S to copy
735 modules out of bss to let's say ALIGN_UP (_end, 8) before cleaning out
736 bss. You'll probably find useful to add total_module_size field to
737 startup.S. In init.c you need to set grub_modbase to the address where
738 modules can be found. You may need grub_modules_get_end () to avoid
739 declaring the space occupied by modules as usable for heap. You can
742 ./grub-mkimage -d grub-core -O $format_id -o test.img hello
744 and then running "hello" in the shell.
746 Once this works, you should think of implementing disk access. Look
747 around disk/ for examples.
749 Then, very importantly, you probably need to implement the actual
750 loader (examples available in loader/)
752 Last step to have minimally usable port is to add support to
753 grub-install to put GRUB in a place where firmware or platform will
756 Next steps are: filling datetime.c, setjmp.S, network (net/drivers),
757 video (video/), halt (lib/), reboot (lib/).
759 Please add your platform to Platform limitations and Supported
760 kernels chapter in user documentation and mention any steps you skipped
761 which result in reduced features or performance. Here is the quick
762 checklist of features. Some of them are less important than others and
763 skipping them is completely ok, just needs to be mentioned in user
767 * Is heap big enough?
769 * Which charset is supported by console?
771 * Does platform have disk driver?
773 * Do you have network card support?
775 * Are you able to retrieve datetime (with date)?
777 * Are you able to set datetime (with date)?
779 * Is serial supported?
781 * Do you have direct disk support?
783 * Do you have direct keyboard support?
785 * Do you have USB support?
787 * Do you support loading through network?
789 * Do you support loading from disk?
791 * Do you support chainloading?
793 * Do you support network chainloading?
795 * Does cpuid command supports checking all CPU features that the
796 user might want conditionalise on (64-bit mode, hypervisor,...)
798 * Do you support hints? How reliable are they?
800 * Does platform have ACPI? If so do "acpi" and "lsacpi" modules work?
802 * Do any of platform-specific operations mentioned in the relevant
803 section of user manual makes sense on your platform?
805 * Does your platform support PCI? If so is there an appropriate
808 * Do you support badram?
811 File: grub-dev.info, Node: Error Handling, Next: CIA, Prev: Porting, Up: Top
816 Error handling in GRUB 2 is based on exception handling model. As C
817 language doesn't directly support exceptions, exception handling
818 behavior is emulated in software.
820 When exception is raised, function must return to calling function.
821 If calling function does not provide handling of the exception it must
822 return back to its calling function and so on, until exception is
823 handled. If exception is not handled before prompt is displayed, error
824 message will be shown to user.
826 Exception information is stored on `grub_errno' global variable. If
827 `grub_errno' variable contains value `GRUB_ERR_NONE', there is no active
828 exception and application can continue normal processing. When
829 `grub_errno' has other value, it is required that application code
830 either handles this error or returns instantly to caller. If function
831 is with return type `grub_err_t' is about to return `GRUB_ERR_NONE', it
832 should not set `grub_errno' to that value. Only set `grub_errno' in
833 cases where there is error situation.
835 Simple exception forwarder.
837 forwarding_example (void)
839 /* Call function that might cause exception. */
842 /* No special exception handler, just forward possible exceptions. */
843 if (grub_errno != GRUB_ERR_NONE)
848 /* All is OK, do more processing. */
850 /* Return OK signal, to caller. */
851 return GRUB_ERR_NONE;
854 Error reporting has two components, the actual error code (of type
855 `grub_err_t') and textual message that will be displayed to user. List
856 of valid error codes is listed in header file `include/grub/err.h'.
857 Textual error message can contain any textual data. At time of writing,
858 error message can contain up to 256 characters (including terminating
859 NUL). To ease error reporting there is a helper function `grub_error'
860 that allows easier formatting of error messages and should be used
861 instead of writing directly to global variables.
863 Example of error reporting.
867 return grub_error (GRUB_ERR_FILE_NOT_FOUND,
868 "Failed to read %s, tried %d times.",
873 If there is a special reason that error code does not need to be
874 taken account, `grub_errno' can be zeroed back to `GRUB_ERR_NONE'. In
875 cases like this all previous error codes should have been handled
876 correctly. This makes sure that there are no unhandled exceptions.
878 Example of zeroing `grub_errno'.
882 /* Try to probe device type 1. */
884 if (grub_errno == GRUB_ERR_NONE)
886 /* Device type 1 was found on system. */
888 return GRUB_ERR_NONE;
890 /* Zero out error code. */
891 grub_errno = GRUB_ERR_NONE;
893 /* No device type 1 found, try to probe device type 2. */
894 probe_for_device2 ();
895 if (grub_errno == GRUB_ERR_NONE)
897 /* Device type 2 was found on system. */
899 return GRUB_ERR_NONE;
901 /* Zero out error code. */
902 grub_errno = GRUB_ERR_NONE;
904 /* Return custom error message. */
905 return grub_error (GRUB_ERR_UNKNOWN_DEVICE, "No device type 1 or 2 found.");
908 Some times there is a need to continue processing even if there is a
909 error state in application. In situations like this, there is a needed
910 to save old error state and then call other functions that might fail.
911 To aid in this, there is a error stack implemented. Error state can be
912 pushed to error stack by calling function `grub_error_push ()'. When
913 processing has been completed, `grub_error_pop ()' can be used to pop
914 error state from stack. Error stack contains predefined amount of error
915 stack items. Error stack is protected for overflow and marks these
916 situations so overflow error does not get unseen. If there is no space
917 available to store error message, it is simply discarded and overflow
918 will be marked as happened. When overflow happens, it most likely will
919 corrupt error stack consistency as for pushed error there is no matching
920 pop, but overflow message will be shown to inform user about the
921 situation. Overflow message will be shown at time when prompt is about
924 Example usage of error stack.
925 /* Save possible old error message. */
928 /* Do your stuff here. */
929 call_possibly_failing_function ();
931 if (grub_errno != GRUB_ERR_NONE)
933 /* Inform rest of the code that there is error (grub_errno
934 is set). There is no pop here as we want both error states
939 /* Restore old error state by popping previous item from stack. */
943 File: grub-dev.info, Node: CIA, Next: BIOS port memory map, Prev: Error Handling, Up: Top
948 If you have commit access, please setup CIA in your Bazaar config so
949 those in IRC receive notification of your commits.
951 In `~/.bazaar/bazaar.conf', add "cia_send_revno = true".
952 Optionally, you can also add "cia_user = myusername" if you'd like CIA
953 service to use a specific account (for statistical purpose).
955 In the `.bzr/branch/branch.conf' of your checkout branch, "set
956 nickname = /path_to_this_branch" and "cia_project = GNU GRUB".
958 Additionally, please set cia_send_revno in the [DEFAULT] section of
959 your `~/.bazaar/bazaar.conf'. E.g.:
962 cia_send_revno = true
964 Remember to install cia-clients (Debian/Ubuntu package) to be able
967 Keep in mind Bazaar sends notifications for all commits to branches
968 that have this setting, regardless of whether they're bound branches
969 (checkouts) or not. So if you make local commits in a non-bound branch
970 and it bothers you that others can read them, do not use this setting.
973 File: grub-dev.info, Node: BIOS port memory map, Next: Video Subsystem, Prev: CIA, Up: Top
975 8 BIOS port memory map
976 **********************
979 --------------------------------------------------------------------
980 0 0x1000 - 1 BIOS and real mode interrupts
981 0x07BE 0x07FF Partition table passed to another
983 ? 0x2000 - 1 Real mode stack
984 0x7C00 0x7D00 - 1 Boot sector
986 0x68000 0x78000 - 1 Disk buffer
987 ? 0x80000 - 1 Protected mode stack
989 ? 0xA0000 - 1 Extended BIOS Data Area
990 0xA0000 0xC0000 - 1 Video RAM
991 0xC0000 0x100000 - 1 BIOS
992 0x100000 ? Heap and module code
995 File: grub-dev.info, Node: Video Subsystem, Next: PFF2 Font File Format, Prev: BIOS port memory map, Up: Top
1000 This document contains specification for Video Subsystem for GRUB2.
1001 Currently only the usage interface is described in this document.
1002 Internal structure of how video drivers are registering and how video
1003 driver manager works are not included here.
1009 * Example usage of Video API::
1012 File: grub-dev.info, Node: Video API, Next: Bitmap API, Up: Video Subsystem
1017 9.1.1 grub_video_setup
1018 ----------------------
1022 grub_video_setup (unsigned int width, unsigned int height, unsigned int mode_type);
1026 Driver will use information provided to it to select best possible
1027 video mode and switch to it. Supported values for `mode_type' are
1028 `GRUB_VIDEO_MODE_TYPE_INDEX_COLOR' for index color modes,
1029 `GRUB_VIDEO_MODE_TYPE_RGB' for direct RGB color modes and
1030 `GRUB_VIDEO_MODE_TYPE_DOUBLE_BUFFERED' for double buffering. When
1031 requesting RGB mode, highest bits per pixel mode will be selected.
1032 When requesting Index color mode, mode with highest number of
1033 colors will be selected. If all parameters are specified as zero,
1034 video adapter will try to figure out best possible mode and
1035 initialize it, platform specific differences are allowed here. If
1036 there is no mode matching request, error X will be returned. If
1037 there are no problems, function returns `GRUB_ERR_NONE'.
1039 This function also performs following task upon succesful mode
1040 switch. Active rendering target is changed to screen and viewport
1041 is maximized to allow whole screen to be used when performing
1042 graphics operations. In RGB modes, emulated palette gets 16
1043 entries containing default values for VGA palette, other colors
1044 are defined as black. When switching to Indexed Color mode, driver
1045 may set default VGA palette to screen if the video card allows the
1049 9.1.2 grub_video_restore
1050 ------------------------
1055 grub_video_restore (void);
1059 Video subsystem will deinitialize activated video driver to
1060 restore old state of video device. This can be used to switch back
1063 9.1.3 grub_video_get_info
1064 -------------------------
1069 grub_video_get_info (struct grub_video_mode_info *mode_info);
1071 struct grub_video_mode_info
1073 /* Width of the screen. */
1075 /* Height of the screen. */
1076 unsigned int height;
1077 /* Mode type bitmask. Contains information like is it Index color or
1079 unsigned int mode_type;
1080 /* Bits per pixel. */
1082 /* Bytes per pixel. */
1083 unsigned int bytes_per_pixel;
1084 /* Pitch of one scanline. How many bytes there are for scanline. */
1086 /* In index color mode, number of colors. In RGB mode this is 256. */
1087 unsigned int number_of_colors;
1088 /* Optimization hint how binary data is coded. */
1089 enum grub_video_blit_format blit_format;
1090 /* How many bits are reserved for red color. */
1091 unsigned int red_mask_size;
1092 /* What is location of red color bits. In Index Color mode, this is 0. */
1093 unsigned int red_field_pos;
1094 /* How many bits are reserved for green color. */
1095 unsigned int green_mask_size;
1096 /* What is location of green color bits. In Index Color mode, this is 0. */
1097 unsigned int green_field_pos;
1098 /* How many bits are reserved for blue color. */
1099 unsigned int blue_mask_size;
1100 /* What is location of blue color bits. In Index Color mode, this is 0. */
1101 unsigned int blue_field_pos;
1102 /* How many bits are reserved in color. */
1103 unsigned int reserved_mask_size;
1104 /* What is location of reserved color bits. In Index Color mode,
1106 unsigned int reserved_field_pos;
1111 Software developer can use this function to query properties of
1112 active rendering taget. Information provided here can be used by
1113 other parts of GRUB, like image loaders to convert loaded images
1114 to correct screen format to allow more optimized blitters to be
1115 used. If there there is no configured video driver with active
1116 screen, error `GRUB_ERR_BAD_DEVICE' is returned, otherwise
1117 `mode_info' is filled with valid information and `GRUB_ERR_NONE'
1120 9.1.4 grub_video_get_blit_format
1121 --------------------------------
1125 enum grub_video_blit_format
1126 grub_video_get_blit_format (struct grub_video_mode_info *mode_info);
1128 enum grub_video_blit_format
1130 /* Follow exactly field & mask information. */
1131 GRUB_VIDEO_BLIT_FORMAT_RGBA,
1132 /* Make optimization assumption. */
1133 GRUB_VIDEO_BLIT_FORMAT_R8G8B8A8,
1134 /* Follow exactly field & mask information. */
1135 GRUB_VIDEO_BLIT_FORMAT_RGB,
1136 /* Make optimization assumption. */
1137 GRUB_VIDEO_BLIT_FORMAT_R8G8B8,
1138 /* When needed, decode color or just use value as is. */
1139 GRUB_VIDEO_BLIT_FORMAT_INDEXCOLOR
1144 Used to query how data could be optimized to suit specified video
1145 mode. Returns exact video format type, or a generic one if there
1146 is no definition for the type. For generic formats, use
1147 `grub_video_get_info' to query video color coding settings.
1149 9.1.5 grub_video_set_palette
1150 ----------------------------
1155 grub_video_set_palette (unsigned int start, unsigned int count, struct grub_video_palette_data *palette_data);
1157 struct grub_video_palette_data
1159 grub_uint8_t r; /* Red color value (0-255). */
1160 grub_uint8_t g; /* Green color value (0-255). */
1161 grub_uint8_t b; /* Blue color value (0-255). */
1162 grub_uint8_t a; /* Reserved bits value (0-255). */
1167 Used to setup indexed color palettes. If mode is RGB mode, colors
1168 will be set to emulated palette data. In Indexed Color modes,
1169 palettes will be set to hardware. Color values will be converted
1170 to suit requirements of the video mode. `start' will tell what
1171 hardware color index (or emulated color index) will be set to
1172 according information in first indice of `palette_data', after
1173 that both hardware color index and `palette_data' index will be
1174 incremented until `count' number of colors have been set.
1176 9.1.6 grub_video_get_palette
1177 ----------------------------
1182 grub_video_get_palette (unsigned int start, unsigned int count, struct grub_video_palette_data *palette_data);
1184 struct grub_video_palette_data
1186 grub_uint8_t r; /* Red color value (0-255). */
1187 grub_uint8_t g; /* Green color value (0-255). */
1188 grub_uint8_t b; /* Blue color value (0-255). */
1189 grub_uint8_t a; /* Reserved bits value (0-255). */
1194 Used to query indexed color palettes. If mode is RGB mode, colors
1195 will be copied from emulated palette data. In Indexed Color modes,
1196 palettes will be read from hardware. Color values will be
1197 converted to suit structure format. `start' will tell what
1198 hardware color index (or emulated color index) will be used as a
1199 source for first indice of `palette_data', after that both
1200 hardware color index and `palette_data' index will be incremented
1201 until `count' number of colors have been read.
1203 9.1.7 grub_video_set_viewport
1204 -----------------------------
1209 grub_video_set_viewport (unsigned int x, unsigned int y, unsigned int width, unsigned int height);
1213 Used to specify viewport where draw commands are performed. When
1214 viewport is set, all draw commands coordinates relate to those
1215 specified by `x' and `y'. If draw commands try to draw over
1216 viewport, they are clipped. If developer requests larger than
1217 possible viewport, width and height will be clamped to fit screen.
1218 If `x' and `y' are out of bounds, all functions drawing to screen
1219 will not be displayed. In order to maximize viewport, use
1220 `grub_video_get_info' to query actual screen dimensions and
1221 provide that information to this function.
1223 9.1.8 grub_video_get_viewport
1224 -----------------------------
1229 grub_video_get_viewport (unsigned int *x, unsigned int *y, unsigned int *width, unsigned int *height);
1233 Used to query current viewport dimensions. Software developer can
1234 use this to choose best way to render contents of the viewport.
1236 9.1.9 grub_video_map_color
1237 --------------------------
1242 grub_video_map_color (grub_uint32_t color_name);
1246 Map color can be used to support color themes in GRUB. There will
1247 be collection of color names that can be used to query actual
1248 screen mapped color data. Examples could be
1249 `GRUB_COLOR_CONSOLE_BACKGROUND', `GRUB_COLOR_CONSOLE_TEXT'. The
1250 actual color defines are not specified at this point.
1252 9.1.10 grub_video_map_rgb
1253 -------------------------
1258 grub_video_map_rgb (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue);
1262 Map RGB values to compatible screen color data. Values are
1263 expected to be in range 0-255 and in RGB modes they will be
1264 converted to screen color data. In index color modes, index color
1265 palette will be searched for specified color and then index is
1268 9.1.11 grub_video_map_rgba
1269 --------------------------
1274 grub_video_map_rgba (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue, grub_uint8_t alpha);
1278 Map RGBA values to compatible screen color data. Values are
1279 expected to be in range 0-255. In RGBA modes they will be
1280 converted to screen color data. In index color modes, index color
1281 palette will be searched for best matching color and its index is
1284 9.1.12 grub_video_unmap_color
1285 -----------------------------
1290 grub_video_unmap_color (grub_video_color_t color, grub_uint8_t *red, grub_uint8_t *green, grub_uint8_t *blue, grub_uint8_t *alpha);
1294 Unmap color value from `color' to color channels in `red',
1295 `green', `blue' and `alpha'. Values will be in range 0-255. Active
1296 rendering target will be used for color domain. In case alpha
1297 information is not available in rendering target, it is assumed to
1298 be opaque (having value 255).
1300 9.1.13 grub_video_fill_rect
1301 ---------------------------
1306 grub_video_fill_rect (grub_video_color_t color, int x, int y, unsigned int width, unsigned int height);
1310 Fill specified area limited by given coordinates within specified
1311 viewport. Negative coordinates are accepted in order to allow easy
1312 moving of rectangle within viewport. If coordinates are negative,
1313 area of the rectangle will be shrinken to follow size limits of
1316 Software developer should use either `grub_video_map_color',
1317 `grub_video_map_rgb' or `grub_video_map_rgba' to map requested
1318 color to `color' parameter.
1320 9.1.14 grub_video_blit_glyph
1321 ----------------------------
1326 grub_video_blit_glyph (struct grub_font_glyph *glyph, grub_video_color_t color, int x, int y);
1328 struct grub_font_glyph {
1334 Used to blit glyph to viewport in specified coodinates. If glyph
1335 is at edge of viewport, pixels outside of viewport will be clipped
1336 out. Software developer should use either `grub_video_map_rgb' or
1337 `grub_video_map_rgba' to map requested color to `color' parameter.
1339 9.1.15 grub_video_blit_bitmap
1340 -----------------------------
1345 grub_video_blit_bitmap (struct grub_video_bitmap *bitmap, enum grub_video_blit_operators oper, int x, int y, int offset_x, int offset_y, unsigned int width, unsigned int height);
1347 struct grub_video_bitmap
1352 enum grub_video_blit_operators
1354 GRUB_VIDEO_BLIT_REPLACE,
1355 GRUB_VIDEO_BLIT_BLEND
1360 Used to blit bitmap to viewport in specified coordinates. If part
1361 of bitmap is outside of viewport region, it will be clipped out.
1362 Offsets affect bitmap position where data will be copied from.
1363 Negative values for both viewport coordinates and bitmap offset
1364 coordinates are allowed. If data is looked out of bounds of
1365 bitmap, color value will be assumed to be transparent. If viewport
1366 coordinates are negative, area of the blitted rectangle will be
1367 shrinken to follow size limits of the viewport and bitmap.
1368 Blitting operator `oper' specifies should source pixel replace
1369 data in screen or blend with pixel alpha value.
1371 Software developer should use `grub_video_bitmap_create' or
1372 `grub_video_bitmap_load' to create or load bitmap data.
1374 9.1.16 grub_video_blit_render_target
1375 ------------------------------------
1380 grub_video_blit_render_target (struct grub_video_render_target *source, enum grub_video_blit_operators oper, int x, int y, int offset_x, int offset_y, unsigned int width, unsigned int height);
1382 struct grub_video_render_target {
1383 /* This is private data for video driver. Should not be accessed from elsewhere directly. */
1386 enum grub_video_blit_operators
1388 GRUB_VIDEO_BLIT_REPLACE,
1389 GRUB_VIDEO_BLIT_BLEND
1394 Used to blit source render target to viewport in specified
1395 coordinates. If part of source render target is outside of
1396 viewport region, it will be clipped out. If blitting operator is
1397 specified and source contains alpha values, resulting pixel color
1398 components will be calculated using formula ((src_color *
1399 src_alpha) + (dst_color * (255 - src_alpha)) / 255, if target
1400 buffer has alpha, it will be set to src_alpha. Offsets affect
1401 render target position where data will be copied from. If data is
1402 looked out of bounds of render target, color value will be assumed
1403 to be transparent. Blitting operator `oper' specifies should
1404 source pixel replace data in screen or blend with pixel alpha
1407 9.1.17 grub_video_scroll
1408 ------------------------
1413 grub_video_scroll (grub_video_color_t color, int dx, int dy);
1417 Used to scroll viewport to specified direction. New areas are
1418 filled with specified color. This function is used when screen is
1419 scroller up in video terminal.
1421 9.1.18 grub_video_swap_buffers
1422 ------------------------------
1427 grub_video_swap_buffers (void);
1431 If double buffering is enabled, this swaps frontbuffer and
1432 backbuffer, in order to show values drawn to back buffer. Video
1433 driver is free to choose how this operation is techincally done.
1435 9.1.19 grub_video_create_render_target
1436 --------------------------------------
1441 grub_video_create_render_target (struct grub_video_render_target **result, unsigned int width, unsigned int height, unsigned int mode_type);
1443 struct grub_video_render_target {
1444 /* This is private data for video driver. Should not be accessed from elsewhere directly. */
1449 Driver will use information provided to it to create best fitting
1450 render target. `mode_type' will be used to guide on selecting what
1451 features are wanted for render target. Supported values for
1452 `mode_type' are `GRUB_VIDEO_MODE_TYPE_INDEX_COLOR' for index color
1453 modes, `GRUB_VIDEO_MODE_TYPE_RGB' for direct RGB color modes and
1454 `GRUB_VIDEO_MODE_TYPE_ALPHA' for alpha component.
1456 9.1.20 grub_video_delete_render_target
1457 --------------------------------------
1462 grub_video_delete_render_target (struct grub_video_render_target *target);
1466 Used to delete previously created render target. If `target'
1467 contains `NULL' pointer, nothing will be done. If render target is
1468 correctly destroyed, GRUB_ERR_NONE is returned.
1470 9.1.21 grub_video_set_active_render_target
1471 ------------------------------------------
1476 grub_video_set_active_render_target (struct grub_video_render_target *target);
1480 Sets active render target. If this comand is successful all
1481 drawing commands will be done to specified `target'. There is also
1482 special values for target, `GRUB_VIDEO_RENDER_TARGET_DISPLAY' used
1483 to reference screen's front buffer,
1484 `GRUB_VIDEO_RENDER_TARGET_FRONT_BUFFER' used to reference screen's
1485 front buffer (alias for `GRUB_VIDEO_RENDER_TARGET_DISPLAY') and
1486 `GRUB_VIDEO_RENDER_TARGET_BACK_BUFFER' used to reference back
1487 buffer (if double buffering is enabled). If render target is
1488 correclty switched GRUB_ERR_NONE is returned. In no any event
1489 shall there be non drawable active render target.
1492 9.1.22 grub_video_get_active_render_target
1493 ------------------------------------------
1498 grub_video_get_active_render_target (struct grub_video_render_target **target);
1502 Returns currently active render target. It returns value in
1503 `target' that can be subsequently issued back to
1504 `grub_video_set_active_render_target'.
1507 File: grub-dev.info, Node: Example usage of Video API, Prev: Bitmap API, Up: Video Subsystem
1509 9.2 Example usage of Video API
1510 ==============================
1512 9.2.1 Example of screen setup
1513 -----------------------------
1516 /* Try to initialize video mode 1024 x 768 with direct RGB. */
1517 rc = grub_video_setup (1024, 768, GRUB_VIDEO_MODE_TYPE_RGB);
1518 if (rc != GRUB_ERR_NONE)
1520 /* Fall back to standard VGA Index Color mode. */
1521 rc = grub_video_setup (640, 480, GRUB_VIDEO_MODE_TYPE_INDEX);
1522 if (rc != GRUB_ERR_NONE)
1528 9.2.2 Example of setting up console viewport
1529 --------------------------------------------
1531 grub_uint32_t x, y, width, height;
1532 grub_video_color_t color;
1533 struct grub_font_glyph glyph;
1535 /* Query existing viewport. */
1536 grub_video_get_viewport (&x, &y, &width, &height);
1537 /* Fill background. */
1538 color = grub_video_map_color (GRUB_COLOR_BACKGROUND);
1539 grub_video_fill_rect (color, 0, 0, width, height);
1540 /* Setup console viewport. */
1541 grub_video_set_viewport (x + 10, y + 10, width - 20, height - 20);
1542 grub_video_get_viewport (&x, &y, &width, &height);
1543 color = grub_video_map_color (GRUB_COLOR_CONSOLE_BACKGROUND);
1544 grub_video_fill_rect (color, 0, 0, width, height);
1545 /* Draw text to viewport. */
1546 color = grub_video_map_color (GRUB_COLOR_CONSOLE_TEXT);
1547 grub_font_get_glyph ('X', &glyph);
1548 grub_video_blit_glyph (&glyph, color, 0, 0);
1551 File: grub-dev.info, Node: Bitmap API, Next: Example usage of Video API, Prev: Video API, Up: Video Subsystem
1556 9.3.1 grub_video_bitmap_create
1557 ------------------------------
1560 grub_err_t grub_video_bitmap_create (struct grub_video_bitmap **bitmap, unsigned int width, unsigned int height, enum grub_video_blit_format blit_format)
1564 Creates a new bitmap with given dimensions and blitting format.
1565 Allocated bitmap data can then be modified freely and finally
1566 blitted with `grub_video_blit_bitmap' to rendering target.
1568 9.3.2 grub_video_bitmap_destroy
1569 -------------------------------
1572 grub_err_t grub_video_bitmap_destroy (struct grub_video_bitmap *bitmap);
1576 When bitmap is no longer needed, it can be freed from memory using
1577 this command. `bitmap' is previously allocated bitmap with
1578 `grub_video_bitmap_create' or loaded with `grub_video_bitmap_load'.
1580 9.3.3 grub_video_bitmap_load
1581 ----------------------------
1584 grub_err_t grub_video_bitmap_load (struct grub_video_bitmap **bitmap, const char *filename);
1588 Tries to load given bitmap (`filename') using registered bitmap
1589 loaders. In case bitmap format is not recognized or supported
1590 error `GRUB_ERR_BAD_FILE_TYPE' is returned.
1592 9.3.4 grub_video_bitmap_get_width
1593 ---------------------------------
1596 unsigned int grub_video_bitmap_get_width (struct grub_video_bitmap *bitmap);
1600 Returns bitmap width.
1602 9.3.5 grub_video_bitmap_get_height
1603 ----------------------------------
1606 unsigned int grub_video_bitmap_get_height (struct grub_video_bitmap *bitmap);
1610 Return bitmap height.
1612 9.3.6 grub_video_bitmap_get_mode_info
1613 -------------------------------------
1616 void grub_video_bitmap_get_mode_info (struct grub_video_bitmap *bitmap, struct grub_video_mode_info *mode_info);
1620 Returns bitmap format details in form of `grub_video_mode_info'.
1622 9.3.7 grub_video_bitmap_get_data
1623 --------------------------------
1626 void *grub_video_bitmap_get_data (struct grub_video_bitmap *bitmap);
1630 Return pointer to bitmap data. Contents of the pointed data can be
1631 freely modified. There is no extra protection against going off
1632 the bounds so you have to be carefull how to access the data.
1635 File: grub-dev.info, Node: PFF2 Font File Format, Next: Graphical Menu Software Design, Prev: Video Subsystem, Up: Top
1637 10 PFF2 Font File Format
1638 ************************
1647 File: grub-dev.info, Node: Introduction, Next: File Structure, Up: PFF2 Font File Format
1652 The goal of this format is to provide a bitmap font format that is
1653 simple to use, compact, and cleanly supports Unicode.
1655 10.1.1 Goals of the GRUB Font Format
1656 ------------------------------------
1658 * Simple to read and use. Since GRUB will only be reading the font
1659 files, we are more concerned with making the code to read the font
1660 simple than we are with writing the font.
1662 * Compact storage. The fonts will generally be stored in a small
1663 boot partition where GRUB is located, and this may be on a
1664 removable storage device such as a CD or USB flash drive where
1665 space is more limited than it is on most hard drives.
1667 * Unicode. GRUB should not have to deal with multiple character
1668 encodings. The font should always use Unicode character codes for
1669 simple internationalization.
1671 10.1.2 Why Another Font Format?
1672 -------------------------------
1674 There are many existing bitmap font formats that GRUB could use.
1675 However, there are aspects of these formats that may make them less
1676 than suitable for use in GRUB at this time:
1679 Inefficient storage; uses ASCII to describe properties and
1680 hexadecimal numbers in ASCII for the bitmap rows.
1683 Many format variations such as byte order and bitmap padding (rows
1684 padded to byte, word, etc.) would result in more complex code to
1685 handle the font format.
1688 File: grub-dev.info, Node: File Structure, Next: Font Metrics, Prev: Introduction, Up: PFF2 Font File Format
1693 A file *section* consists of a 4-byte name, a 32-bit big-endian length
1694 (not including the name or length), and then LENGTH more
1695 section-type-specific bytes.
1697 The standard file extension for PFF2 font files is `.pf2'.
1699 10.2.1 Section Types
1700 --------------------
1703 *File type ID* (ASCII string). This must be the first section in
1704 the file. It has length 4 and the contents are the four bytes of
1705 the ASCII string `PFF2'.
1708 *Font name* (ASCII string). This is the full font name including
1709 family, weight, style, and point size. For instance, "Helvetica
1713 *Font family name* (ASCII string). For instance, "Helvetica".
1714 This should be included so that intelligent font substitution can
1718 *Font weight* (ASCII string). Valid values are `bold' and
1719 `normal'. This should be included so that intelligent font
1720 substitution can take place.
1723 *Font slant* (ASCII string). Valid values are `italic' and
1724 `normal'. This should be included so that intelligent font
1725 substitution can take place.
1728 *Font point size* (uint16be).
1731 *Maximum character width in pixels* (uint16be).
1734 *Maximum character height in pixels* (uint16be).
1737 *Ascent in pixels* (uint16be). *Note Font Metrics::, for details.
1740 *Descent in pixels* (uint16be). *Note Font Metrics::, for details.
1743 *Character index.* The character index begins with a 32-bit
1744 big-endian unsigned integer indicating the total size of the
1745 section, not including this size value. For each character, there
1746 is an instance of the following entry structure:
1748 * *Unicode code point.* (32-bit big-endian integer.)
1750 * *Storage flags.* (byte.)
1754 If equal to 000 binary, then the character data is stored
1755 uncompressed beginning at the offset indicated by the
1756 character's *offset* value.
1758 If equal to 001 binary, then the character data is
1759 stored within a compressed character definition block
1760 that begins at the offset within the file indicated by
1761 the character's *offset* value.
1763 * *Offset.* (32-bit big-endian integer.)
1765 A marker that indicates the remainder of the file is data
1766 accessed via the character index (CHIX) section. When
1767 reading this font file, the rest of the file can be ignored
1768 when scanning the sections. The length should be set to -1
1771 Supported data structures:
1773 Character definition Each character definition consists of:
1775 * *Width.* Width of the bitmap in pixels. The bitmap's
1776 extents represent the glyph's bounding box. `uint16be'.
1778 * *Height.* Height of the bitmap in pixels. The bitmap's
1779 extents represent the glyph's bounding box. `uint16be'.
1781 * *X offset.* The number of pixels to shift the bitmap by
1782 horizontally before drawing the character. `int16be'.
1784 * *Y offset.* The number of pixels to shift the bitmap by
1785 vertically before drawing the character. `int16be'.
1787 * *Device width.* The number of pixels to advance
1788 horizontally from this character's origin to the origin
1789 of the next character. `int16be'.
1791 * *Bitmap data.* This is encoded as a string of bits. It
1792 is organized as a row-major, top-down, left-to-right
1793 bitmap. The most significant bit of each byte is taken
1794 to be the leftmost or uppermost bit in the byte. For
1795 the sake of compact storage, rows are not padded to byte
1796 boundaries (i.e., a single byte may contain bits
1797 belonging to multiple rows). The last byte of the
1798 bitmap *is* padded with zero bits in the bits positions
1799 to the right of the last used bit if the bitmap data
1800 does not fill the last byte.
1802 The length of the *bitmap data* field is (WIDTH * HEIGHT
1803 + 7) / 8 using integer arithmetic, which is equivalent
1804 to ceil(WIDTH * HEIGHT / 8) using real number arithmetic.
1806 It remains to be determined whether bitmap fonts usually
1807 make all glyph bitmaps the same height, or if smaller
1808 glyphs are stored with bitmaps having a lesser height.
1809 In the latter case, the baseline would have to be used
1810 to calculate the location the bitmap should be anchored
1815 File: grub-dev.info, Node: Font Metrics, Prev: File Structure, Up: PFF2 Font File Format
1820 * Ascent. The distance from the baseline to the top of most
1821 characters. Note that in some cases characters may extend above
1824 * Descent. The distance from the baseline to the bottom of most
1825 characters. Note that in some cases characters may extend below
1828 * Leading. The amount of space, in pixels, to leave between the
1829 descent of one line of text and the ascent of the next line. This
1830 metrics is not specified in the current file format; instead, the
1831 font rendering engine calculates a reasonable leading value based
1832 on the other font metrics.
1834 * Horizonal leading. The amount of space, in pixels, to leave
1835 horizontally between the left and right edges of two adjacent
1836 glyphs. The *device width* field determines the effective leading
1837 value that is used to render the font.
1839 [Please fill this in.
1842 An illustration of how the various font metrics apply to characters.
1845 File: grub-dev.info, Node: Graphical Menu Software Design, Next: Copying This Manual, Prev: PFF2 Font File Format, Up: Top
1847 11 Graphical Menu Software Design
1848 *********************************
1853 * Startup Sequence::
1855 * Command Line Window::
1858 File: grub-dev.info, Node: Introduction_2, Next: Startup Sequence, Up: Graphical Menu Software Design
1863 The `gfxmenu' module provides a graphical menu interface for GRUB 2. It
1864 functions as an alternative to the menu interface provided by the
1865 `normal' module, which uses the grub terminal interface to display a
1866 menu on a character-oriented terminal.
1868 The graphical menu uses the GRUB video API, which is currently for
1869 the VESA BIOS extensions (VBE) 2.0+. This is supported on the i386-pc
1870 platform. However, the graphical menu itself does not depend on using
1871 VBE, so if another GRUB video driver were implemented, the `gfxmenu'
1872 graphical menu would work on the new video driver as well.
1875 File: grub-dev.info, Node: Startup Sequence, Next: GUI Components, Prev: Introduction_2, Up: Graphical Menu Software Design
1877 11.2 Startup Sequence
1878 =====================
1880 * grub_enter_normal_mode [normal/main.c]
1882 * grub_normal_execute [normal/main.c]
1884 * read_config_file [normal/main.c]
1886 * (When `gfxmenu.mod' is loaded with `insmod', it will call
1887 `grub_menu_viewer_register()' to register itself.)
1889 * GRUB_MOD_INIT (gfxmenu) [gfxmenu/gfxmenu.c]
1891 * grub_menu_viewer_register [kern/menu_viewer.c]
1893 * grub_menu_viewer_show_menu [kern/menu_viewer.c]
1895 * get_current_menu_viewer() [kern/menu_viewer.c]
1897 * show_menu() [gfxmenu/gfxmenu.c]
1899 * grub_gfxmenu_model_new [gfxmenu/model.c]
1901 * grub_gfxmenu_view_new [gfxmenu/view.c]
1903 * set_graphics_mode [gfxmenu/view.c]
1905 * grub_gfxmenu_view_load_theme [gfxmenu/theme_loader.c]
1908 File: grub-dev.info, Node: GUI Components, Next: Command Line Window, Prev: Startup Sequence, Up: Graphical Menu Software Design
1913 The graphical menu implements a GUI component system that supports a
1914 container-based layout system. Components can be added to containers,
1915 and containers (which are a type of component) can then be added to
1916 other containers, to form a tree of components. Currently, the root
1917 component of this tree is a `canvas' component, which allows manual
1918 layout of its child components.
1920 Components (non-container):
1930 * list (currently hard coded to be a boot menu list)
1940 The GUI component instances are created by the theme loader in
1941 `gfxmenu/theme_loader.c' when a theme is loaded. Theme files specify
1942 statements such as `+vbox{ +label { text="Hello" } +label{ text="World"
1943 } }' to add components to the component tree root. By nesting the
1944 component creation statements in the theme file, the instantiated
1945 components are nested the same way.
1947 When a component is added to a container, that new child is
1948 considered *owned* by the container. Great care should be taken if the
1949 caller retains a reference to the child component, since it will be
1950 destroyed if its parent container is destroyed. A better choice
1951 instead of storing a pointer to the child component is to use the
1952 component ID to find the desired component. Component IDs do not have
1953 to be unique (it is often useful to have multiple components with an ID
1954 of "__timeout__", for instance).
1956 In order to access and use components in the component tree, there
1957 are two functions (defined in `gfxmenu/gui_util.c') that are
1958 particularly useful:
1960 * `grub_gui_find_by_id (root, id, callback, userdata)':
1962 This function ecursively traverses the component tree rooted at
1963 ROOT, and for every component that has an ID equal to ID, calls
1964 the function pointed to by CALLBACK with the matching component
1965 and the void pointer USERDATA as arguments. The callback function
1966 can do whatever is desired to use the component passed in.
1968 * `grub_gui_iterate_recursively (root, callback, userdata)':
1970 This function calls the function pointed to by CALLBACK for every
1971 component that is a descendant of ROOT in the component tree.
1972 When the callback function is called, the component and the void
1973 pointer USERDATA as arguments. The callback function can do
1974 whatever is desired to use the component passed in.
1977 File: grub-dev.info, Node: Command Line Window, Prev: GUI Components, Up: Graphical Menu Software Design
1979 11.4 Command Line Window
1980 ========================
1982 The terminal window used to provide command line access within the
1983 graphical menu is managed by `gfxmenu/view.c'. The `gfxterm' terminal
1984 is used, and it has been modified to allow rendering to an offscreen
1985 render target to allow it to be composed into the double buffering
1986 system that the graphical menu view uses. This is bad for performance,
1987 however, so it would probably be a good idea to make it possible to
1988 temporarily disable double buffering as long as the terminal window is
1989 visible. There are still unresolved problems that occur when commands
1990 are executed from the terminal window that change the graphics mode.
1991 It's possible that making `grub_video_restore()' return to the graphics
1992 mode that was in use before `grub_video_setup()' was called might fix
1993 some of the problems.
1996 File: grub-dev.info, Node: Copying This Manual, Next: Index, Prev: Graphical Menu Software Design, Up: Top
1998 Appendix A Copying This Manual
1999 ******************************
2003 * GNU Free Documentation License:: License for copying this manual.
2006 File: grub-dev.info, Node: GNU Free Documentation License, Up: Copying This Manual
2008 A.1 GNU Free Documentation License
2009 ==================================
2011 Version 1.2, November 2002
2013 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
2014 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
2016 Everyone is permitted to copy and distribute verbatim copies
2017 of this license document, but changing it is not allowed.
2021 The purpose of this License is to make a manual, textbook, or other
2022 functional and useful document "free" in the sense of freedom: to
2023 assure everyone the effective freedom to copy and redistribute it,
2024 with or without modifying it, either commercially or
2025 noncommercially. Secondarily, this License preserves for the
2026 author and publisher a way to get credit for their work, while not
2027 being considered responsible for modifications made by others.
2029 This License is a kind of "copyleft", which means that derivative
2030 works of the document must themselves be free in the same sense.
2031 It complements the GNU General Public License, which is a copyleft
2032 license designed for free software.
2034 We have designed this License in order to use it for manuals for
2035 free software, because free software needs free documentation: a
2036 free program should come with manuals providing the same freedoms
2037 that the software does. But this License is not limited to
2038 software manuals; it can be used for any textual work, regardless
2039 of subject matter or whether it is published as a printed book.
2040 We recommend this License principally for works whose purpose is
2041 instruction or reference.
2043 1. APPLICABILITY AND DEFINITIONS
2045 This License applies to any manual or other work, in any medium,
2046 that contains a notice placed by the copyright holder saying it
2047 can be distributed under the terms of this License. Such a notice
2048 grants a world-wide, royalty-free license, unlimited in duration,
2049 to use that work under the conditions stated herein. The
2050 "Document", below, refers to any such manual or work. Any member
2051 of the public is a licensee, and is addressed as "you". You
2052 accept the license if you copy, modify or distribute the work in a
2053 way requiring permission under copyright law.
2055 A "Modified Version" of the Document means any work containing the
2056 Document or a portion of it, either copied verbatim, or with
2057 modifications and/or translated into another language.
2059 A "Secondary Section" is a named appendix or a front-matter section
2060 of the Document that deals exclusively with the relationship of the
2061 publishers or authors of the Document to the Document's overall
2062 subject (or to related matters) and contains nothing that could
2063 fall directly within that overall subject. (Thus, if the Document
2064 is in part a textbook of mathematics, a Secondary Section may not
2065 explain any mathematics.) The relationship could be a matter of
2066 historical connection with the subject or with related matters, or
2067 of legal, commercial, philosophical, ethical or political position
2070 The "Invariant Sections" are certain Secondary Sections whose
2071 titles are designated, as being those of Invariant Sections, in
2072 the notice that says that the Document is released under this
2073 License. If a section does not fit the above definition of
2074 Secondary then it is not allowed to be designated as Invariant.
2075 The Document may contain zero Invariant Sections. If the Document
2076 does not identify any Invariant Sections then there are none.
2078 The "Cover Texts" are certain short passages of text that are
2079 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
2080 that says that the Document is released under this License. A
2081 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
2082 be at most 25 words.
2084 A "Transparent" copy of the Document means a machine-readable copy,
2085 represented in a format whose specification is available to the
2086 general public, that is suitable for revising the document
2087 straightforwardly with generic text editors or (for images
2088 composed of pixels) generic paint programs or (for drawings) some
2089 widely available drawing editor, and that is suitable for input to
2090 text formatters or for automatic translation to a variety of
2091 formats suitable for input to text formatters. A copy made in an
2092 otherwise Transparent file format whose markup, or absence of
2093 markup, has been arranged to thwart or discourage subsequent
2094 modification by readers is not Transparent. An image format is
2095 not Transparent if used for any substantial amount of text. A
2096 copy that is not "Transparent" is called "Opaque".
2098 Examples of suitable formats for Transparent copies include plain
2099 ASCII without markup, Texinfo input format, LaTeX input format,
2100 SGML or XML using a publicly available DTD, and
2101 standard-conforming simple HTML, PostScript or PDF designed for
2102 human modification. Examples of transparent image formats include
2103 PNG, XCF and JPG. Opaque formats include proprietary formats that
2104 can be read and edited only by proprietary word processors, SGML or
2105 XML for which the DTD and/or processing tools are not generally
2106 available, and the machine-generated HTML, PostScript or PDF
2107 produced by some word processors for output purposes only.
2109 The "Title Page" means, for a printed book, the title page itself,
2110 plus such following pages as are needed to hold, legibly, the
2111 material this License requires to appear in the title page. For
2112 works in formats which do not have any title page as such, "Title
2113 Page" means the text near the most prominent appearance of the
2114 work's title, preceding the beginning of the body of the text.
2116 A section "Entitled XYZ" means a named subunit of the Document
2117 whose title either is precisely XYZ or contains XYZ in parentheses
2118 following text that translates XYZ in another language. (Here XYZ
2119 stands for a specific section name mentioned below, such as
2120 "Acknowledgements", "Dedications", "Endorsements", or "History".)
2121 To "Preserve the Title" of such a section when you modify the
2122 Document means that it remains a section "Entitled XYZ" according
2125 The Document may include Warranty Disclaimers next to the notice
2126 which states that this License applies to the Document. These
2127 Warranty Disclaimers are considered to be included by reference in
2128 this License, but only as regards disclaiming warranties: any other
2129 implication that these Warranty Disclaimers may have is void and
2130 has no effect on the meaning of this License.
2134 You may copy and distribute the Document in any medium, either
2135 commercially or noncommercially, provided that this License, the
2136 copyright notices, and the license notice saying this License
2137 applies to the Document are reproduced in all copies, and that you
2138 add no other conditions whatsoever to those of this License. You
2139 may not use technical measures to obstruct or control the reading
2140 or further copying of the copies you make or distribute. However,
2141 you may accept compensation in exchange for copies. If you
2142 distribute a large enough number of copies you must also follow
2143 the conditions in section 3.
2145 You may also lend copies, under the same conditions stated above,
2146 and you may publicly display copies.
2148 3. COPYING IN QUANTITY
2150 If you publish printed copies (or copies in media that commonly
2151 have printed covers) of the Document, numbering more than 100, and
2152 the Document's license notice requires Cover Texts, you must
2153 enclose the copies in covers that carry, clearly and legibly, all
2154 these Cover Texts: Front-Cover Texts on the front cover, and
2155 Back-Cover Texts on the back cover. Both covers must also clearly
2156 and legibly identify you as the publisher of these copies. The
2157 front cover must present the full title with all words of the
2158 title equally prominent and visible. You may add other material
2159 on the covers in addition. Copying with changes limited to the
2160 covers, as long as they preserve the title of the Document and
2161 satisfy these conditions, can be treated as verbatim copying in
2164 If the required texts for either cover are too voluminous to fit
2165 legibly, you should put the first ones listed (as many as fit
2166 reasonably) on the actual cover, and continue the rest onto
2169 If you publish or distribute Opaque copies of the Document
2170 numbering more than 100, you must either include a
2171 machine-readable Transparent copy along with each Opaque copy, or
2172 state in or with each Opaque copy a computer-network location from
2173 which the general network-using public has access to download
2174 using public-standard network protocols a complete Transparent
2175 copy of the Document, free of added material. If you use the
2176 latter option, you must take reasonably prudent steps, when you
2177 begin distribution of Opaque copies in quantity, to ensure that
2178 this Transparent copy will remain thus accessible at the stated
2179 location until at least one year after the last time you
2180 distribute an Opaque copy (directly or through your agents or
2181 retailers) of that edition to the public.
2183 It is requested, but not required, that you contact the authors of
2184 the Document well before redistributing any large number of
2185 copies, to give them a chance to provide you with an updated
2186 version of the Document.
2190 You may copy and distribute a Modified Version of the Document
2191 under the conditions of sections 2 and 3 above, provided that you
2192 release the Modified Version under precisely this License, with
2193 the Modified Version filling the role of the Document, thus
2194 licensing distribution and modification of the Modified Version to
2195 whoever possesses a copy of it. In addition, you must do these
2196 things in the Modified Version:
2198 A. Use in the Title Page (and on the covers, if any) a title
2199 distinct from that of the Document, and from those of
2200 previous versions (which should, if there were any, be listed
2201 in the History section of the Document). You may use the
2202 same title as a previous version if the original publisher of
2203 that version gives permission.
2205 B. List on the Title Page, as authors, one or more persons or
2206 entities responsible for authorship of the modifications in
2207 the Modified Version, together with at least five of the
2208 principal authors of the Document (all of its principal
2209 authors, if it has fewer than five), unless they release you
2210 from this requirement.
2212 C. State on the Title page the name of the publisher of the
2213 Modified Version, as the publisher.
2215 D. Preserve all the copyright notices of the Document.
2217 E. Add an appropriate copyright notice for your modifications
2218 adjacent to the other copyright notices.
2220 F. Include, immediately after the copyright notices, a license
2221 notice giving the public permission to use the Modified
2222 Version under the terms of this License, in the form shown in
2225 G. Preserve in that license notice the full lists of Invariant
2226 Sections and required Cover Texts given in the Document's
2229 H. Include an unaltered copy of this License.
2231 I. Preserve the section Entitled "History", Preserve its Title,
2232 and add to it an item stating at least the title, year, new
2233 authors, and publisher of the Modified Version as given on
2234 the Title Page. If there is no section Entitled "History" in
2235 the Document, create one stating the title, year, authors,
2236 and publisher of the Document as given on its Title Page,
2237 then add an item describing the Modified Version as stated in
2238 the previous sentence.
2240 J. Preserve the network location, if any, given in the Document
2241 for public access to a Transparent copy of the Document, and
2242 likewise the network locations given in the Document for
2243 previous versions it was based on. These may be placed in
2244 the "History" section. You may omit a network location for a
2245 work that was published at least four years before the
2246 Document itself, or if the original publisher of the version
2247 it refers to gives permission.
2249 K. For any section Entitled "Acknowledgements" or "Dedications",
2250 Preserve the Title of the section, and preserve in the
2251 section all the substance and tone of each of the contributor
2252 acknowledgements and/or dedications given therein.
2254 L. Preserve all the Invariant Sections of the Document,
2255 unaltered in their text and in their titles. Section numbers
2256 or the equivalent are not considered part of the section
2259 M. Delete any section Entitled "Endorsements". Such a section
2260 may not be included in the Modified Version.
2262 N. Do not retitle any existing section to be Entitled
2263 "Endorsements" or to conflict in title with any Invariant
2266 O. Preserve any Warranty Disclaimers.
2268 If the Modified Version includes new front-matter sections or
2269 appendices that qualify as Secondary Sections and contain no
2270 material copied from the Document, you may at your option
2271 designate some or all of these sections as invariant. To do this,
2272 add their titles to the list of Invariant Sections in the Modified
2273 Version's license notice. These titles must be distinct from any
2274 other section titles.
2276 You may add a section Entitled "Endorsements", provided it contains
2277 nothing but endorsements of your Modified Version by various
2278 parties--for example, statements of peer review or that the text
2279 has been approved by an organization as the authoritative
2280 definition of a standard.
2282 You may add a passage of up to five words as a Front-Cover Text,
2283 and a passage of up to 25 words as a Back-Cover Text, to the end
2284 of the list of Cover Texts in the Modified Version. Only one
2285 passage of Front-Cover Text and one of Back-Cover Text may be
2286 added by (or through arrangements made by) any one entity. If the
2287 Document already includes a cover text for the same cover,
2288 previously added by you or by arrangement made by the same entity
2289 you are acting on behalf of, you may not add another; but you may
2290 replace the old one, on explicit permission from the previous
2291 publisher that added the old one.
2293 The author(s) and publisher(s) of the Document do not by this
2294 License give permission to use their names for publicity for or to
2295 assert or imply endorsement of any Modified Version.
2297 5. COMBINING DOCUMENTS
2299 You may combine the Document with other documents released under
2300 this License, under the terms defined in section 4 above for
2301 modified versions, provided that you include in the combination
2302 all of the Invariant Sections of all of the original documents,
2303 unmodified, and list them all as Invariant Sections of your
2304 combined work in its license notice, and that you preserve all
2305 their Warranty Disclaimers.
2307 The combined work need only contain one copy of this License, and
2308 multiple identical Invariant Sections may be replaced with a single
2309 copy. If there are multiple Invariant Sections with the same name
2310 but different contents, make the title of each such section unique
2311 by adding at the end of it, in parentheses, the name of the
2312 original author or publisher of that section if known, or else a
2313 unique number. Make the same adjustment to the section titles in
2314 the list of Invariant Sections in the license notice of the
2317 In the combination, you must combine any sections Entitled
2318 "History" in the various original documents, forming one section
2319 Entitled "History"; likewise combine any sections Entitled
2320 "Acknowledgements", and any sections Entitled "Dedications". You
2321 must delete all sections Entitled "Endorsements."
2323 6. COLLECTIONS OF DOCUMENTS
2325 You may make a collection consisting of the Document and other
2326 documents released under this License, and replace the individual
2327 copies of this License in the various documents with a single copy
2328 that is included in the collection, provided that you follow the
2329 rules of this License for verbatim copying of each of the
2330 documents in all other respects.
2332 You may extract a single document from such a collection, and
2333 distribute it individually under this License, provided you insert
2334 a copy of this License into the extracted document, and follow
2335 this License in all other respects regarding verbatim copying of
2338 7. AGGREGATION WITH INDEPENDENT WORKS
2340 A compilation of the Document or its derivatives with other
2341 separate and independent documents or works, in or on a volume of
2342 a storage or distribution medium, is called an "aggregate" if the
2343 copyright resulting from the compilation is not used to limit the
2344 legal rights of the compilation's users beyond what the individual
2345 works permit. When the Document is included in an aggregate, this
2346 License does not apply to the other works in the aggregate which
2347 are not themselves derivative works of the Document.
2349 If the Cover Text requirement of section 3 is applicable to these
2350 copies of the Document, then if the Document is less than one half
2351 of the entire aggregate, the Document's Cover Texts may be placed
2352 on covers that bracket the Document within the aggregate, or the
2353 electronic equivalent of covers if the Document is in electronic
2354 form. Otherwise they must appear on printed covers that bracket
2355 the whole aggregate.
2359 Translation is considered a kind of modification, so you may
2360 distribute translations of the Document under the terms of section
2361 4. Replacing Invariant Sections with translations requires special
2362 permission from their copyright holders, but you may include
2363 translations of some or all Invariant Sections in addition to the
2364 original versions of these Invariant Sections. You may include a
2365 translation of this License, and all the license notices in the
2366 Document, and any Warranty Disclaimers, provided that you also
2367 include the original English version of this License and the
2368 original versions of those notices and disclaimers. In case of a
2369 disagreement between the translation and the original version of
2370 this License or a notice or disclaimer, the original version will
2373 If a section in the Document is Entitled "Acknowledgements",
2374 "Dedications", or "History", the requirement (section 4) to
2375 Preserve its Title (section 1) will typically require changing the
2380 You may not copy, modify, sublicense, or distribute the Document
2381 except as expressly provided for under this License. Any other
2382 attempt to copy, modify, sublicense or distribute the Document is
2383 void, and will automatically terminate your rights under this
2384 License. However, parties who have received copies, or rights,
2385 from you under this License will not have their licenses
2386 terminated so long as such parties remain in full compliance.
2388 10. FUTURE REVISIONS OF THIS LICENSE
2390 The Free Software Foundation may publish new, revised versions of
2391 the GNU Free Documentation License from time to time. Such new
2392 versions will be similar in spirit to the present version, but may
2393 differ in detail to address new problems or concerns. See
2394 `http://www.gnu.org/copyleft/'.
2396 Each version of the License is given a distinguishing version
2397 number. If the Document specifies that a particular numbered
2398 version of this License "or any later version" applies to it, you
2399 have the option of following the terms and conditions either of
2400 that specified version or of any later version that has been
2401 published (not as a draft) by the Free Software Foundation. If
2402 the Document does not specify a version number of this License,
2403 you may choose any version ever published (not as a draft) by the
2404 Free Software Foundation.
2406 A.1.1 ADDENDUM: How to use this License for your documents
2407 ----------------------------------------------------------
2409 To use this License in a document you have written, include a copy of
2410 the License in the document and put the following copyright and license
2411 notices just after the title page:
2413 Copyright (C) YEAR YOUR NAME.
2414 Permission is granted to copy, distribute and/or modify this document
2415 under the terms of the GNU Free Documentation License, Version 1.2
2416 or any later version published by the Free Software Foundation;
2417 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
2418 Texts. A copy of the license is included in the section entitled ``GNU
2419 Free Documentation License''.
2421 If you have Invariant Sections, Front-Cover Texts and Back-Cover
2422 Texts, replace the "with...Texts." line with this:
2424 with the Invariant Sections being LIST THEIR TITLES, with
2425 the Front-Cover Texts being LIST, and with the Back-Cover Texts
2428 If you have Invariant Sections without Cover Texts, or some other
2429 combination of the three, merge those two alternatives to suit the
2432 If your document contains nontrivial examples of program code, we
2433 recommend releasing these examples in parallel under your choice of
2434 free software license, such as the GNU General Public License, to
2435 permit their use in free software.
2438 File: grub-dev.info, Node: Index, Prev: Copying This Manual, Up: Top
2446 * FDL, GNU Free Documentation License: GNU Free Documentation License.
2453 Node: Getting the source code
\x7f1786
2454 Node: Coding style
\x7f2666
2455 Node: Naming Conventions
\x7f3071
2456 Node: Functions
\x7f3354
2457 Node: Variables
\x7f4221
2459 Node: Macros
\x7f5925
2460 Node: Comments
\x7f6256
2461 Node: Multi-Line Comments
\x7f7018
2462 Node: Finding your way around
\x7f7649
2463 Node: Contributing Changes
\x7f10846
2464 Node: Getting started
\x7f11923
2465 Node: Typical Developer Experience
\x7f15969
2466 Node: When you are approved for write access to project's files
\x7f17012
2467 Node: Porting
\x7f18442
2468 Node: Error Handling
\x7f30182
2470 Node: BIOS port memory map
\x7f36314
2471 Node: Video Subsystem
\x7f37184
2472 Node: Video API
\x7f37656
2473 Node: Example usage of Video API
\x7f55910
2474 Node: Bitmap API
\x7f57466
2475 Node: PFF2 Font File Format
\x7f59997
2476 Node: Introduction
\x7f60237
2477 Node: File Structure
\x7f61740
2478 Node: Font Metrics
\x7f66647
2479 Node: Graphical Menu Software Design
\x7f67751
2480 Node: Introduction_2
\x7f68043
2481 Node: Startup Sequence
\x7f68777
2482 Node: GUI Components
\x7f69640
2483 Node: Command Line Window
\x7f72245
2484 Node: Copying This Manual
\x7f73197
2485 Node: GNU Free Documentation License
\x7f73453
2486 Node: Index
\x7f95865