mode table (@pxref{Boot information format}) must be available to the
kernel.
+If bit 3 in the @samp{flags} word is set, the multiboot information
+must be in tagged format.
+
If bit 16 in the @samp{flags} word is set, then the fields at offsets
12-28 in the Multiboot header are valid, and the boot loader should use
them instead of the fields in the actual executable header to calculate
@table @samp
@item EAX
-Must contain the magic value @samp{0x2BADB002}; the presence of this
+Must contain the magic value @samp{0x2BADB002} if Boot info is non-tagged and @samp{0x3BADB002} otherwise; the presence of this
value indicates to the operating system that it was loaded by a
Multiboot-compliant boot loader (e.g. as opposed to another type of
boot loader that the operating system can also be loaded from).
@node Boot information format
-@section Boot information format
-
-FIXME: Split this chapter like the chapter ``OS image format''.
+@section Boot information
+@subsection Boot information format
Upon entry to the operating system, the @code{EBX} register contains the
physical address of a @dfn{Multiboot information} data structure,
operating system's responsibility to avoid overwriting this memory until
it is done using it.
+@subsection Basic tags structure
+Boot information can be passed in one of two formats: pointer-based
+or tag-based. Tag-based format must be used if and only it was requested
+in multiboot header. Every tag begins with following fields:
+
+@example
+@group
+ +-------------------+
+0 | type |
+4-7 | size |
+ +-------------------+
+@end group
+@end example
+
+@samp{type} contains an identifier of contents of the rest of the tag.
+@samp{size} contains the size of tag including header fields.
+Tags follow one another without any gaps. Tags are terminated by a tag of type @samp{0} and size @samp{8}.
+
+@subsection Basic non-tagged structure
The format of the Multiboot information structure (as defined so far)
follows:
information structure to be expanded in the future without breaking
anything.
+@subsection Basic memory information
If bit 0 in the @samp{flags} word is set, then the @samp{mem_*} fields
are valid. @samp{mem_lower} and @samp{mem_upper} indicate the amount of
lower and upper memory, respectively, in kilobytes. Lower memory starts
upper memory is maximally the address of the first upper memory hole
minus 1 megabyte. It is not guaranteed to be this value.
+Corresponding tag is:
+
+@example
+@group
+ +-------------------+
+0 | type = 4 |
+4 | size = 16 |
+8 | mem_lower |
+12-15 | mem_upper |
+ +-------------------+
+@end group
+@end example
+
+@subsection BIOS Boot device
If bit 1 in the @samp{flags} word is set, then the @samp{boot_device}
field is valid, and indicates which @sc{bios} disk device the boot
loader loaded the OS image from. If the OS image was not loaded from a
@samp{part1} will be 5, and @samp{part2} and @samp{part3} will both be
0xFF.
+Corresponding tag is:
+@example
+@group
+ +-------------------+
+0 | type = 5 |
+4 | size = 20 |
+8 | biosdev |
+12 | partition |
+16-19 | sub-parition |
+ +-------------------+
+@end group
+@end example
+
+@subsection Boot command line
If bit 2 of the @samp{flags} longword is set, the @samp{cmdline} field
is valid, and contains the physical address of the command line to
be passed to the kernel. The command line is a normal C-style
-zero-terminated string.
+UTF-8 zero-terminated string.
+
+Corresponding tag is:
+@example
+@group
+ +-------------------+
+0 | type = 1 |
+4 | size |
+8-xx | string |
+ +-------------------+
+@end group
+@end example
+
+@samp{string} contains zero-terminated UTF-8 string padded to have length divisible by 4.
+@subsection Modules
If bit 3 of the @samp{flags} is set, then the @samp{mods} fields
indicate to the kernel what boot modules were loaded along with the
kernel image, and where they can be found. @samp{mods_count} contains
The first two fields contain the start and end addresses of the boot
module itself. The @samp{string} field provides an arbitrary string to
be associated with that particular boot module; it is a zero-terminated
-ASCII string, just like the kernel command line. The @samp{string} field
+UTF-8 string, just like the kernel command line. The @samp{string} field
may be 0 if there is no string associated with the module. Typically the
string might be a command line (e.g. if the operating system treats boot
modules as executable programs), or a pathname (e.g. if the operating
is specific to the operating system. The @samp{reserved} field must be
set to 0 by the boot loader and ignored by the operating system.
+Corresponding tag is:
+
+@example
+@group
+ +-------------------+
+0 | type = 3 |
+4 | size |
+8 | mod_start |
+12 | mod_end |
+16-xx | string |
+ +-------------------+
+@end group
+@end example
+
+Tag is padded in the way to have size divisible by 4.
+
+One tag appears per module.
+
+@subsection Symbols
@strong{Caution:} Bits 4 & 5 are mutually exclusive.
If bit 4 in the @samp{flags} word is set, then the following fields in
@samp{shdr_num} may be 0, indicating no symbols, even if bit 5 in the
@samp{flags} word is set.
+@subsection Memory map
If bit 6 in the @samp{flags} word is set, then the @samp{mmap_*} fields
are valid, and indicate the address and length of a buffer containing a
memory map of the machine provided by the @sc{bios}. @samp{mmap_addr} is
The map provided is guaranteed to list all standard @sc{ram} that should
be available for normal use.
+The corresponding tag is
+@example
+@group
+ +-------------------+
+0 | type = 6 |
+4 | size |
+8-xx | entries |
+ +-------------------+
+@end group
+@end example
+
+@subsection Drives table
If bit 7 in the @samp{flags} is set, then the @samp{drives_*} fields
are valid, and indicate the address of the physical address of the first
drive structure and the size of drive structures. @samp{drives_addr}
array may contain any number of I/O ports that are not related to the
drive actually (such as @sc{dma} controller's ports).
+@subsection Configuration table
If bit 8 in the @samp{flags} is set, then the @samp{config_table} field
is valid, and indicates the address of the @sc{rom} configuration table
returned by the @dfn{GET CONFIGURATION} @sc{bios} call. If the @sc{bios}
call fails, then the size of the table must be @emph{zero}.
+@subsection Boot loader name
If bit 9 in the @samp{flags} is set, the @samp{boot_loader_name} field
is valid, and contains the physical address of the name of a boot
loader booting the kernel. The name is a normal C-style zero-terminated
string.
+Corresponding tag is:
+@example
+@group
+ +-------------------+
+0 | type = 2 |
+4 | size |
+8-xx | string |
+ +-------------------+
+@end group
+@end example
+
+@samp{string} contains zero-terminated UTF-8 string padded to have length divisible by 4.
+
+@subsection APM table
If bit 10 in the @samp{flags} is set, the @samp{apm_table} field is
valid, and contains the physical address of an @sc{apm} table defined as
below:
@uref{http://www.microsoft.com/hwdev/busbios/amp_12.htm, Advanced Power
Management (APM) BIOS Interface Specification}, for more information.
+@subsection VBE info
If bit 11 in the @samp{flags} is set, the @sc{vbe} table is available.
The fields @samp{vbe_control_info} and @samp{vbe_mode_info} contain
Multiboot boot loaders may simulate @sc{vbe} on non-@sc{vbe} modes, as
if they were @sc{vbe} modes.
+Corresponding tag is:
+@example
+@group
+ +-------------------+
+0 | type = 7 |
+4 | size = 784 |
+8 | vbe_mode |
+10 | vbe_interface_seg |
+12 | vbe_interface_off |
+14 | vbe_interface_len |
+16 | vbe_control_info |
+528-783 | vbe_mode_info |
+ +-------------------+
+@end group
+@end example
+
+Notice that the tag contains VBE control and mode information structures directly rather than a pointer to them
+
+@subsection Framebuffer info
If bit 12 in the @samp{flags} is set, the @sc{Framebuffer} table is available.
The field @samp{framebuffer_addr} contains framebuffer physical address. This field is 64-bit wide but bootloader @dfn{should} set it under 4GiB if possible for compatibility with payloads which aren't aware of PAE or amd64. The field @samp{framebuffer_pitch} contains pitch in bytes. The fields @samp{framebuffer_width}, @samp{framebuffer_height} contain framebuffer dimensions in pixels. The field @samp{framebuffer_bpp} contains number of bits per pixel. If @samp{framebuffer_type} is set to 0 it means indexed color. In this case color_info is defined as follows:
+-------------+
0 | red_value |
1 | green_value |
-2 | blue_value |
+2-2 | blue_value |
+-------------+
@end group
@end example
If @samp{framebuffer_type} is set to 2 it means EGA text. In this case @samp{framebuffer_width} and @samp{framebuffer_height} are expressed in characters and not in pixels. @samp{framebuffer_bpp} is equal 16 (16 bits per character) and @samp{framebuffer_pitch} is expressed in bytes per text line.
All further values of @samp{framebuffer_type} are reserved for future expansion
+Corresponding tag is:
+@example
+@group
+ +--------------------+
+0 | type = 8 |
+4 | size |
+8 | framebuffer_addr |
+16 | framebuffer_pitch |
+20 | framebuffer_width |
+24 | framebuffer_height |
+28 | framebuffer_bpp |
+29 | framebuffer_type |
+30 | color_info |
+ +--------------------+
+@end group
+@end example
+
+If @samp{framebuffer_type} is @samp{0} color_info has the following format:
+
+@example
+@group
+ +---------------------------------+
+0 | framebuffer_palette_num_colors |
+4-xx | framebuffer_palette |
+ +---------------------------------+
+@end group
+@end example
+
+With @samp{framebuffer_palette_num_colors} and @samp{framebuffer_palette} having the same format as in non-tagged version
+
+Note: @samp{framebuffer_palette} contains the palette and not its address.
+
+If @samp{framebuffer_type} is @samp{1} or @samp{2} color_info has the same format as non-tagged version.
+
@node Examples
@chapter Examples
projects / thirdparty / grub.git / commitdiff
