From: Vladimir 'phcoder' Serbinenko <phcoder@gmail.com>
Date: Mon, 4 Jan 2010 21:05:52 +0000 (+0100)
Subject: Tagged mbi
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=81bbea0515bf51111f592e8a38e8562a36be1129;p=thirdparty%2Fgrub.git

Tagged mbi
---

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 1de486585..d8ecb8a00 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -414,6 +414,9 @@ If bit 2 in the @samp{flags} word is set, information about the video
 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
@@ -515,7 +518,7 @@ must have the following state:
 
 @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).
@@ -578,9 +581,8 @@ changed them during the switch to 32-bit mode.
 
 
 @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,
@@ -595,6 +597,25 @@ memory reserved for the kernel and boot modules, of course). It is the
 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:
 
@@ -655,6 +676,7 @@ field also functions as a version indicator, allowing the Multiboot
 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
@@ -663,6 +685,20 @@ possible value for lower memory is 640 kilobytes. The value returned for
 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
@@ -705,11 +741,39 @@ partition on a disk partitioned in conventional DOS style, then
 @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
@@ -734,7 +798,7 @@ set. Each module structure is formatted as follows:
 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
@@ -742,6 +806,25 @@ system treats boot modules as files in a file system), but its exact use
 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
@@ -795,6 +878,7 @@ details as to how to read the section header(s)). Note that
 @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
@@ -824,6 +908,18 @@ indicated a reserved area.
 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}
@@ -878,16 +974,32 @@ unsigned two-bytes integers, and is terminated with zero. Note that the
 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:
@@ -920,6 +1032,7 @@ bytes, and the others are 2 bytes. See
 @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
@@ -942,6 +1055,25 @@ The fields for the graphics table are designed for @sc{vbe}, but
 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:
@@ -959,7 +1091,7 @@ The field @samp{framebuffer_addr} contains framebuffer physical address. This fi
         +-------------+
 0       | red_value   |
 1       | green_value |
-2       | blue_value  |
+2-2     | blue_value  |
         +-------------+
 @end group
 @end example
@@ -981,6 +1113,40 @@ If @samp{framebuffer_type} is set to 1 it means direct RGB color. Then color_typ
 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