vbatts/grub
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

* docs/grub-dev.texi (Finding your way around): Update for 1.99

Browse source 
build system.
(Getting started): GRUB is developed in Bazaar now, not Subversion.

(Comment): Fix typo.
(Getting started): General copy-editing.
(Typical Development Experience): Likewise.
(Error Handling): Likewise.
(Video API): Likewise.
This commit is contained in:
Colin Watson 2011-04-09 03:39:47 +01:00
parent 2cf09e3258
commit 536ce85a8d
2 changed files with 76 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
ChangeLog
View file

@ -1,3 +1,15 @@
2011-04-09 Colin Watson <cjwatson@ubuntu.com>
* docs/grub-dev.texi (Finding your way around): Update for 1.99
build system.
(Getting started): GRUB is developed in Bazaar now, not Subversion.
(Comment): Fix typo.
(Getting started): General copy-editing.
(Typical Development Experience): Likewise.
(Error Handling): Likewise.
(Video API): Likewise.
2011-04-09 Colin Watson <cjwatson@ubuntu.com> 2011-04-09 Colin Watson <cjwatson@ubuntu.com>
* docs/grub-dev.texi: Replace MoinMoin syntax with Texinfo syntax * docs/grub-dev.texi: Replace MoinMoin syntax with Texinfo syntax

117
docs/grub-dev.texi
View file

@ -169,7 +169,7 @@ If a macro is global, its name must be prefixed with GRUB_ and must consist of o
All comments shall be C-style comments, of the form @samp{/* @dots{} */}. All comments shall be C-style comments, of the form @samp{/* @dots{} */}.
Comments shall be placed only on a line be themselves. They shall not be placed together with code, variable declarations, or other non-comment entities. A comment should be placed immediately preceding the entity it describes. Comments shall be placed only on a line by themselves. They shall not be placed together with code, variable declarations, or other non-comment entities. A comment should be placed immediately preceding the entity it describes.
Acceptable: Acceptable:
@example @example
@ -214,74 +214,85 @@ The opening @samp{/*} and closing @samp{*/} should be placed together on a line
Here is a brief map of the GRUB code base. Here is a brief map of the GRUB code base.
GRUB uses Autoconf, but not (yet) Automake. The top-level build rules are GRUB uses Autoconf and Automake, with most of the Automake input generated
in @file{configure.ac}, @file{Makefile.in}, and @file{conf/*.rmk}. Each by AutoGen. The top-level build rules are in @file{configure.ac},
@file{conf/*.rmk} file represents a particular target configuration, and is @file{grub-core/Makefile.core.def}, and @file{Makefile.util.def}. Each
processed into GNU Make rules by @file{genmk.rb} (which you only need to block in a @file{*.def} file represents a build target, and specifies the
source files used to build it on various platforms. The @file{*.def} files
are processed into AutoGen input by @file{gentpl.py} (which you only need to
look at if you are extending the build system). If you are adding a new look at if you are extending the build system). If you are adding a new
module which follows an existing pattern, such as a new command or a new module which follows an existing pattern, such as a new command or a new
filesystem implementation, it is usually easiest to grep @file{conf/*.rmk} filesystem implementation, it is usually easiest to grep
for an existing example of that pattern to find out where it should be @file{grub-core/Makefile.core.def} and @file{Makefile.util.def} for an
added. existing example of that pattern to find out where it should be added.
In general, code that may be run at boot time is in a subdirectory of
@file{grub-core}, while code that is only run from within a full operating
system is in a subdirectory of the top level.
Low-level boot code, such as the MBR implementation on PC BIOS systems, is Low-level boot code, such as the MBR implementation on PC BIOS systems, is
in the @file{boot/} directory. in the @file{grub-core/boot/} directory.
The GRUB kernel is in @file{kern/}. This contains core facilities such as The GRUB kernel is in @file{grub-core/kern/}. This contains core facilities
the device, disk, and file frameworks, environment variable handling, list such as the device, disk, and file frameworks, environment variable
processing, and so on. The kernel should contain enough to get up to a handling, list processing, and so on. The kernel should contain enough to
rescue prompt. Header files for kernel facilities, among others, are in get up to a rescue prompt. Header files for kernel facilities, among
@file{include/}. others, are in @file{include/}.
Terminal implementations are in @file{term/}. Terminal implementations are in @file{grub-core/term/}.
Disk access code is spread across @file{disk/} (for accessing the disk Disk access code is spread across @file{grub-core/disk/} (for accessing the
devices themselves), @file{partmap/} (for interpreting partition table disk devices themselves), @file{grub-core/partmap/} (for interpreting
data), and @file{fs/} (for accessing filesystems). Note that, with the odd partition table data), and @file{grub-core/fs/} (for accessing filesystems).
specialised exception, GRUB only contains code to @emph{read} from Note that, with the odd specialised exception, GRUB only contains code to
filesystems and tries to avoid containing any code to @emph{write} to @emph{read} from filesystems and tries to avoid containing any code to
filesystems; this lets us confidently assure users that GRUB cannot be @emph{write} to filesystems; this lets us confidently assure users that GRUB
responsible for filesystem corruption. cannot be responsible for filesystem corruption.
PCI and USB bus handling is in @file{bus/}. PCI and USB bus handling is in @file{grub-core/bus/}.
Video handling code is in @file{video/}. The graphical menu system uses Video handling code is in @file{grub-core/video/}. The graphical menu
this heavily, but is in a separate directory, @file{gfxmenu/}. system uses this heavily, but is in a separate directory,
@file{grub-core/gfxmenu/}.
Most commands are implemented by files in @file{commands/}, with the Most commands are implemented by files in @file{grub-core/commands/}, with
following exceptions: the following exceptions:
@itemize @itemize
@item @item
A few core commands live in @file{kern/corecmd.c}. A few core commands live in @file{grub-core/kern/corecmd.c}.
@item @item
Commands related to normal mode live under @file{normal/}. Commands related to normal mode live under @file{grub-core/normal/}.
@item @item
Commands that load and boot kernels live under @file{loader/}. Commands that load and boot kernels live under @file{grub-core/loader/}.
@item @item
The @samp{loopback} command is really a disk device, and so lives in The @samp{loopback} command is really a disk device, and so lives in
@file{disk/loopback.c}. @file{grub-core/disk/loopback.c}.
@item @item
The @samp{gettext} command lives under @file{gettext/}. The @samp{gettext} command lives under @file{grub-core/gettext/}.
@item @item
The @samp{loadfont} and @samp{lsfonts} commands live under @file{font/}. The @samp{loadfont} and @samp{lsfonts} commands live under
@file{grub-core/font/}.
@item @item
The @samp{serial}, @samp{terminfo}, and @samp{background_image} commands The @samp{serial}, @samp{terminfo}, and @samp{background_image} commands
live under @file{term/}. live under @file{grub-core/term/}.
@item @item
The @samp{efiemu_*} commands live under @file{efiemu/}. The @samp{efiemu_*} commands live under @file{grub-core/efiemu/}.
@end itemize @end itemize
There are a few other special-purpose exceptions; grep for them if they There are a few other special-purpose exceptions; grep for them if they
matter to you. matter to you.
Utility programs meant to be run from a full operating system are in
@file{util/}.
@node Contributing Changes @node Contributing Changes
@chapter Contributing changes @chapter Contributing changes
@c By YoshinoriOkuji, VesaJääskeläinen, ColinWatson @c By YoshinoriOkuji, VesaJääskeläinen, ColinWatson
@ -317,10 +328,10 @@ anymore.
@itemize @itemize
@item Always use latest GRUB 2 source code. So get that first. @item 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 on SVN repository. 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 Bazaar (bzr) repository.
Please check Savannah's GRUB project page for details how to get newest BZR: Please check Savannah's GRUB project page for details how to get newest bzr:
@uref{http://savannah.gnu.org/bzr/?group=grub, GRUB 2 BZR Repository} @uref{http://savannah.gnu.org/bzr/?group=grub, GRUB 2 bzr Repository}
@item Compile it and try it out. @item Compile it and try it out.
@ -342,7 +353,7 @@ 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 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. 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 to development so you 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. do not need to change much of the code when your patch is being reviewed.
(see @ref{Coding style}) (see @ref{Coding style})
@ -357,11 +368,11 @@ discuss it beforehand on grub-devel mailing list.
@item Test your change. @item Test your change.
Test that your change works properly. Try it out couple of times. Preferably on different systems. And try to find problems from it. Test that your change works properly. Try it out a couple of times, preferably on different systems, and try to find problems with it.
@item Publish your change. @item Publish your change.
When you are happy with your change. First make sure it is compilable with 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 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, 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 what it changes and so on. Please be prepared to receive even discouraging
@ -379,15 +390,15 @@ for copyright agreement, process can take some time and is mandatory
in order to get your changes integrated. in order to get your changes integrated.
If you are not on grub-devel to respond to questions, most likely your patch If you are not on grub-devel to respond to questions, most likely your patch
will not be accepted. Also if there comes problems from your changes later on, will not be accepted. Also if problems arise from your changes later on,
it would be preferably that you also fix the problem. So stay around it would be preferable that you also fix the problem. So stay around
for a while. for a while.
@item Your patch is accepted. @item Your patch is accepted.
Good job! Your patch will no be integrated to GRUB 2 main line and if it didn't break a thing it will be publically available when next release will be done. 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 welcomed to do further improvements :) Now you are welcome to do further improvements :)
@end itemize @end itemize
@node Typical Developer Experience @node Typical Developer Experience
@ -400,7 +411,7 @@ The typical experience for a developer in this project is the following:
@item You show some result in the mailing list or the IRC. @item You show some result in the mailing list or the IRC.
@item You are getting to be known to other developers. @item You are getting to be known to other developers.
@item You accumulate significant amount of contribution, so copyright assignment is processed. @item You accumulate significant amount of contribution, so copyright assignment is processed.
@item You are free to check in your changes by your own, legally speaking. @item You are free to check in your changes on your own, legally speaking.
@end enumerate @end enumerate
At this point, it is rather annoying that you ought to ask somebody else every At this point, it is rather annoying that you ought to ask somebody else every
@ -444,7 +455,7 @@ doesn't direcly support exceptions, exception handling behavior is emulated
in software. in software.
When exception is raised, function must return to calling function. If calling When exception is raised, function must return to calling function. If calling
function does not provide handling of the exception it must return back to it's function does not provide handling of the exception it must return back to its
calling function and so on, until exception is handled. If exception is not calling function and so on, until exception is handled. If exception is not
handled before prompt is displayed, error message will be shown to user. handled before prompt is displayed, error message will be shown to user.
@ -541,11 +552,11 @@ error state and then call other functions that might fail. To aid in this,
there is a error stack implemented. Error state can be pushed to error stack there is a error stack implemented. Error state can be pushed to error stack
by calling function @code{grub_error_push ()}. When processing has been completed, by calling function @code{grub_error_push ()}. When processing has been completed,
@code{grub_error_pop ()} can be used to pop error state from stack. Error stack @code{grub_error_pop ()} can be used to pop error state from stack. Error stack
contains predefined amount of error stack items. Error stack is proteced for contains predefined amount of error stack items. Error stack is protected for
overflow and marks these situations so overflow error does not get unseen. overflow and marks these situations so overflow error does not get unseen.
If there is no space available to store error message, it is simply discarded If there is no space available to store error message, it is simply discarded
and overflow will be marked as happened. When overflow happens, it most likely and overflow will be marked as happened. When overflow happens, it most likely
will corrupt error stack consistency as for pushed error there is no matching will corrupt error stack consistency as for pushed error there is no matching
pop, but overflow message will be shown to inform user about the situation. pop, but overflow message will be shown to inform user about the situation.
Overflow message will be shown at time when prompt is about to be drawn. Overflow message will be shown at time when prompt is about to be drawn.
@ -646,7 +657,7 @@ grub_video_setup (unsigned int width, unsigned int height, unsigned int mode_typ
Driver will use information provided to it to select best possible video mode and switch to it. Supported values for @code{mode_type} are @code{GRUB_VIDEO_MODE_TYPE_INDEX_COLOR} for index color modes, @code{GRUB_VIDEO_MODE_TYPE_RGB} for direct RGB color modes and @code{GRUB_VIDEO_MODE_TYPE_DOUBLE_BUFFERED} for double buffering. When requesting RGB mode, highest bits per pixel mode will be selected. When requesting Index color mode, mode with highest number of colors will be selected. If all parameters are specified as zero, video adapter will try to figure out best possible mode and initialize it, platform specific differences are allowed here. If there is no mode matching request, error X will be returned. If there are no problems, function returns @code{GRUB_ERR_NONE}. Driver will use information provided to it to select best possible video mode and switch to it. Supported values for @code{mode_type} are @code{GRUB_VIDEO_MODE_TYPE_INDEX_COLOR} for index color modes, @code{GRUB_VIDEO_MODE_TYPE_RGB} for direct RGB color modes and @code{GRUB_VIDEO_MODE_TYPE_DOUBLE_BUFFERED} for double buffering. When requesting RGB mode, highest bits per pixel mode will be selected. When requesting Index color mode, mode with highest number of colors will be selected. If all parameters are specified as zero, video adapter will try to figure out best possible mode and initialize it, platform specific differences are allowed here. If there is no mode matching request, error X will be returned. If there are no problems, function returns @code{GRUB_ERR_NONE}.
This function also performs following task upon succesful mode switch. Active rendering target is changed to screen and viewport is maximized to allow whole screen to be used when performing graphics operations. In RGB modes, emulated palette get's 16 entries containing default values for VGA palette, other colors are defined as black. When switching to Indexed Color mode, driver may set default VGA palette to screen if the video card allows the operation. This function also performs following task upon succesful mode switch. Active rendering target is changed to screen and viewport is maximized to allow whole screen to be used when performing graphics operations. In RGB modes, emulated palette gets 16 entries containing default values for VGA palette, other colors are defined as black. When switching to Indexed Color mode, driver may set default VGA palette to screen if the video card allows the operation.
@end itemize @end itemize
@ -836,7 +847,7 @@ grub_video_map_rgb (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue);
@end example @end example
@item Description: @item Description:
Map RGB values to compatible screen color data. Values are excepted to be in range 0-255 and in RGB modes they will be converted to screen color data. In index color modes, index color palette will be searched for specified color and then index is returned. Map RGB values to compatible screen color data. Values are expected to be in range 0-255 and in RGB modes they will be converted to screen color data. In index color modes, index color palette will be searched for specified color and then index is returned.
@end itemize @end itemize
@subsection grub_video_map_rgba @subsection grub_video_map_rgba
@ -849,7 +860,7 @@ grub_video_map_rgba (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue, gr
@end example @end example
@item Description: @item Description:
Map RGBA values to compatible screen color data. Values are excepted to be in range 0-255. In RGBA modes they will be converted to screen color data. In index color modes, index color palette will be searched for best matching color and it's index is returned. Map RGBA values to compatible screen color data. Values are expected to be in range 0-255. In RGBA modes they will be converted to screen color data. In index color modes, index color palette will be searched for best matching color and its index is returned.
@end itemize @end itemize
@subsection grub_video_unmap_color @subsection grub_video_unmap_color
@ -1016,7 +1027,7 @@ grub_video_set_active_render_target (struct grub_video_render_target *target);
@end example @end example
@item Description: @item Description:
Set's active render target. If this comand is successful all drawing commands will be done to specified @code{target}. There is also special values for target, @code{GRUB_VIDEO_RENDER_TARGET_DISPLAY} used to reference screen's front buffer, @code{GRUB_VIDEO_RENDER_TARGET_FRONT_BUFFER} used to reference screen's front buffer (alias for @code{GRUB_VIDEO_RENDER_TARGET_DISPLAY}) and @code{GRUB_VIDEO_RENDER_TARGET_BACK_BUFFER} used to reference back buffer (if double buffering is enabled). If render target is correclty switched GRUB_ERR_NONE is returned. In no any event shall there be non drawable active render target. Sets active render target. If this comand is successful all drawing commands will be done to specified @code{target}. There is also special values for target, @code{GRUB_VIDEO_RENDER_TARGET_DISPLAY} used to reference screen's front buffer, @code{GRUB_VIDEO_RENDER_TARGET_FRONT_BUFFER} used to reference screen's front buffer (alias for @code{GRUB_VIDEO_RENDER_TARGET_DISPLAY}) and @code{GRUB_VIDEO_RENDER_TARGET_BACK_BUFFER} used to reference back buffer (if double buffering is enabled). If render target is correclty switched GRUB_ERR_NONE is returned. In no any event shall there be non drawable active render target.
@end itemize @end itemize
@subsection grub_video_get_active_render_target @subsection grub_video_get_active_render_target