All global symbols (i.e. functions, variables, types, and macros) must have the prefix grub_ or GRUB_. The all capital form is used only by macros.
@node Functions
@section Functions
If a function is global, its name must be prefixed with grub_ and must consist of only small letters. If the function belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for file systems, its name is prefixed with grub_fs_. If a function is for FAT file system but not for all file systems, its name is prefixed with grub_fs_fat_. The hierarchy is noted this way.
After a prefix, a function name must start with a verb (such as get or is). It must not be a noun. Some kind of abbreviation is permitted, as long as it wouldn't make code less readable (e.g. init).
If a function is local, its name may not start with any prefix. It must start with a verb.
@node Variables
@section Variables
The rule is mostly the same as functions, as noted above. If a variable is global, its name must be prefixed with grub_ and must consist of only small letters. If the variable belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for dynamic loading, its name is prefixed with grub_dl_. If a variable is for ELF but not for all dynamic loading systems, its name is prefixed with grub_dl_elf_.
After a prefix, a variable name must start with a noun or an adjective (such as name or long) and it should end with a noun. Some kind of abbreviation is permitted, as long as it wouldn't make code less readable (e.g. i18n).
If a variable is global in the scope of a single file (i.e. it is declared with static), its name may not start with any prefix. It must start with a noun or an adjective.
If a variable is local, you may choose any shorter name, as long as it wouldn't make code less readable (e.g. i).
@node Types
@section Types
The name of a type must be prefixed with grub_ and must consist of only small letters. If the type belongs to a specific function module, the name must also be prefixed with the module name. For example, if a type is for OS loaders, its name is prefixed with grub_loader_. If a type is for Multiboot but not for all OS loaders, its name is prefixed with grub_loader_linux_.
The name must be suffixed with _t, to emphasize the fact that it is a type but not a variable or a function.
@node Macros
@section Macros
If a macro is global, its name must be prefixed with GRUB_ and must consist of only large letters. Other rules are the same as functions or variables, depending on whether a macro is used like a function or a variable.
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.
Acceptable:
@example
/* The page # that is the front buffer. */
int displayed_page;
/* The page # that is the back buffer. */
int render_page;
@end example
Unacceptable:
@example
int displayed_page; /* The page # that is the front buffer. */
int render_page; /* The page # that is the back buffer. */
@end example
@node Multi-Line Comments
@section Multi-Line Comments
Comments spanning multiple lines shall be formatted with all lines after the first aligned with the first line.
Asterisk characters should not be repeated a the start of each subsequent line.
If you intended to make changes to GRUB Legacy (<=0.97) those are not accepted
anymore.
@menu
* Getting started::
* Typical Developer Experience::
* When you are approved for write access to project's files::
@end menu
@node Getting started
@section Getting started
@itemize
@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.
Please check Savannah's GRUB project page for details how to get newest BZR:
If you are asked to modify your patch, please do that and resubmit it for
review. If your change is large you are required to submit a copyright
agreement to FSF. Please keep in mind that if you are asked to submit
for copyright agreement, process can take some time and is mandatory
in order to get your changes integrated.
If you are not on grub-devel to respond to questions, most likely your patch
will not be accepted. Also if there comes problems from your changes later on,
it would be preferably that you also fix the problem. So stay around
for a while.
@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.
Now you are welcomed to do further improvements :)
@end itemize
@node Typical Developer Experience
@section Typical Developer Experience
The typical experience for a developer in this project is the following:
@enumerate
@item You find yourself wanting to do something (e.g. fixing a bug).
@item You show some result in the mailing list or the IRC.
@item You are getting to be known to other developers.
@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.
@end enumerate
At this point, it is rather annoying that you ought to ask somebody else every
change to be checked in. For efficiency, it is far better, if you can commit
it yourself. Therefore, our policy is to give you the write permission to our
official repository, once you have shown your skill and will,
and the FSF clerks have dealt with your copyright assignment.
@node When you are approved for write access to project's files
@section When you are approved for write access to project's files
As you might know, GRUB is hosted on
@url{https://savannah.gnu.org/projects/grub Savannah}, thus the membership
is managed by Savannah. This means that, if you want to be a member of this
project:
@enumerate
@item You need to create your own account on Savannah.
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.
@end itemize
@subsection grub_video_restore
@itemize
@item Prototype:
@example
grub_err_t
grub_video_restore (void);
@end example
@item Description:
Video subsystem will deinitialize activated video driver to restore old state of video device. This can be used to switch back to text mode.
Software developer can use this function to query properties of active rendering taget. Information provided here can be used by other parts of GRUB, like image loaders to convert loaded images to correct screen format to allow more optimized blitters to be used. If there there is no configured video driver with active screen, error @code{GRUB_ERR_BAD_DEVICE} is returned, otherwise @code{mode_info} is filled with valid information and @code{GRUB_ERR_NONE} is returned.
Used to query how data could be optimized to suit specified video mode. Returns exact video format type, or a generic one if there is no definition for the type. For generic formats, use @code{grub_video_get_info} to query video color coding settings.
Used to setup indexed color palettes. If mode is RGB mode, colors will be set to emulated palette data. In Indexed Color modes, palettes will be set to hardware. Color values will be converted to suit requirements of the video mode. @code{start} will tell what hardware color index (or emulated color index) will be set to according information in first indice of @code{palette_data}, after that both hardware color index and @code{palette_data} index will be incremented until @code{count} number of colors have been set.
Used to query indexed color palettes. If mode is RGB mode, colors will be copied from emulated palette data. In Indexed Color modes, palettes will be read from hardware. Color values will be converted to suit structure format. @code{start} will tell what hardware color index (or emulated color index) will be used as a source for first indice of @code{palette_data}, after that both hardware color index and @code{palette_data} index will be incremented until @code{count} number of colors have been read.
Used to specify viewport where draw commands are performed. When viewport is set, all draw commands coordinates relate to those specified by @code{x} and @code{y}. If draw commands try to draw over viewport, they are clipped. If developer requests larger than possible viewport, width and height will be clamped to fit screen. If @code{x} and @code{y} are out of bounds, all functions drawing to screen will not be displayed. In order to maximize viewport, use @code{grub_video_get_info} to query actual screen dimensions and provide that information to this function.
Map color can be used to support color themes in GRUB. There will be collection of color names that can be used to query actual screen mapped color data. Examples could be @code{GRUB_COLOR_CONSOLE_BACKGROUND}, @code{GRUB_COLOR_CONSOLE_TEXT}. The actual color defines are not specified at this point.
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 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.
Unmap color value from @code{color} to color channels in @code{red}, @code{green}, @code{blue} and @code{alpha}. Values will be in range 0-255. Active rendering target will be used for color domain. In case alpha information is not available in rendering target, it is assumed to be opaque (having value 255).
grub_video_fill_rect (grub_video_color_t color, int x, int y, unsigned int width, unsigned int height);
@end example
@item Description:
Fill specified area limited by given coordinates within specified viewport. Negative coordinates are accepted in order to allow easy moving of rectangle within viewport. If coordinates are negative, area of the rectangle will be shrinken to follow size limits of the viewport.
Software developer should use either @code{grub_video_map_color}, @code{grub_video_map_rgb} or @code{grub_video_map_rgba} to map requested color to @code{color} parameter.
Used to blit glyph to viewport in specified coodinates. If glyph is at edge of viewport, pixels outside of viewport will be clipped out. Software developer should use either @code{grub_video_map_rgb} or @code{grub_video_map_rgba} to map requested color to @code{color} parameter.
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);
Used to blit bitmap to viewport in specified coordinates. If part of bitmap is outside of viewport region, it will be clipped out. Offsets affect bitmap position where data will be copied from. Negative values for both viewport coordinates and bitmap offset coordinates are allowed. If data is looked out of bounds of bitmap, color value will be assumed to be transparent. If viewport coordinates are negative, area of the blitted rectangle will be shrinken to follow size limits of the viewport and bitmap. Blitting operator @code{oper} specifies should source pixel replace data in screen or blend with pixel alpha value.
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);
@end example
@example
struct grub_video_render_target @{
/* This is private data for video driver. Should not be accessed from elsewhere directly. */
Used to blit source render target to viewport in specified coordinates. If part of source render target is outside of viewport region, it will be clipped out. If blitting operator is specified and source contains alpha values, resulting pixel color components will be calculated using formula ((src_color * src_alpha) + (dst_color * (255 - src_alpha)) / 255, if target buffer has alpha, it will be set to src_alpha. Offsets affect render target position where data will be copied from. If data is looked out of bounds of render target, color value will be assumed to be transparent. Blitting operator @code{oper} specifies should source pixel replace data in screen or blend with pixel alpha value.
grub_video_scroll (grub_video_color_t color, int dx, int dy);
@end example
@item Description:
Used to scroll viewport to specified direction. New areas are filled with specified color. This function is used when screen is scroller up in video terminal.
@end itemize
@subsection grub_video_swap_buffers
@itemize
@item Prototype:
@example
grub_err_t
grub_video_swap_buffers (void);
@end example
@item Description:
If double buffering is enabled, this swaps frontbuffer and backbuffer, in order to show values drawn to back buffer. Video driver is free to choose how this operation is techincally done.
@end itemize
@subsection grub_video_create_render_target
@itemize
@item Prototype:
@example
grub_err_t
grub_video_create_render_target (struct grub_video_render_target **result, unsigned int width, unsigned int height, unsigned int mode_type);
@end example
@example
struct grub_video_render_target @{
/* This is private data for video driver. Should not be accessed from elsewhere directly. */
Driver will use information provided to it to create best fitting render target. @code{mode_type} will be used to guide on selecting what features are wanted for render target. 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_ALPHA} for alpha component.
Used to delete previously created render target. If @code{target} contains @code{NULL} pointer, nothing will be done. If render target is correctly destroyed, GRUB_ERR_NONE is returned.
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.
Returns currently active render target. It returns value in @code{target} that can be subsequently issued back to @code{grub_video_set_active_render_target}.
Creates a new bitmap with given dimensions and blitting format. Allocated bitmap data can then be modified freely and finally blitted with @code{grub_video_blit_bitmap} to rendering target.
When bitmap is no longer needed, it can be freed from memory using this command. @code{bitmap} is previously allocated bitmap with @code{grub_video_bitmap_create} or loaded with @code{grub_video_bitmap_load}.
Tries to load given bitmap (@code{filename}) using registered bitmap loaders. In case bitmap format is not recognized or supported error @code{GRUB_ERR_BAD_FILE_TYPE} is returned.
Return pointer to bitmap data. Contents of the pointed data can be freely modified. There is no extra protection against going off the bounds so you have to be carefull how to access the data.
@end itemize
@node PFF2 Font File Format
@chapter PFF2 Font File Format
@c Author: Colin D. Bennett <colin@gibibit.com>
@c Date: 8 January 2009
@menu
* Introduction::
* File Structure::
* Font Metrics::
@end menu
@node Introduction
@section Introduction
The goal of this format is to provide a bitmap font format that is simple to