+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename multiboot.info
-@set VERSION 0.6.95
-@settitle Multiboot Specification version @value{VERSION}
-@c Unify all our little indices for now.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-@c %**end of header
-
-@footnotestyle separate
-@paragraphindent 3
-@finalout
-
-@copying
-Copyright @copyright{} 1995,96 Bryan Ford <baford@@cs.utah.edu>
-
-Copyright @copyright{} 1995,96 Erich Stefan Boleyn <erich@@uruk.org>
-
-Copyright @copyright{} 1999,2000,2001,2002,2005,2006 Free Software Foundation, Inc.
-
-@quotation
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries a copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified
-versions.
-@end quotation
-@end copying
-
-@dircategory Kernel
-@direntry
-* Multiboot Specification: (multiboot). Multiboot Specification.
-@end direntry
-
-@titlepage
-@sp 10
-@title The Multiboot Specification version @value{VERSION}
-@author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn, Kunihiro Ishiguro
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@finalout
-@headings double
-
-@ifnottex
-@node Top
-@top Multiboot Specification
-
-This file documents Multiboot Specification, the proposal for the boot
-sequence standard. This edition documents version @value{VERSION}.
-
-@insertcopying
-@end ifnottex
-
-@menu
-* Overview::
-* Terminology::
-* Specification::
-* Examples::
-* History::
-* Index::
-@end menu
-
-
-@node Overview
-@chapter Introduction to Multiboot Specification
-
-This chapter describes some rough information on the Multiboot
-Specification. Note that this is not a part of the specification itself.
-
-@menu
-* Motivation::
-* Architecture::
-* Operating systems::
-* Boot sources::
-* Boot-time configuration::
-* Convenience to operating systems::
-* Boot modules::
-@end menu
-
-
-@node Motivation
-@section The background of Multiboot Specification
-
-Every operating system ever created tends to have its own boot loader.
-Installing a new operating system on a machine generally involves
-installing a whole new set of boot mechanisms, each with completely
-different install-time and boot-time user interfaces. Getting multiple
-operating systems to coexist reliably on one machine through typical
-@dfn{chaining} mechanisms can be a nightmare. There is little or no
-choice of boot loaders for a particular operating system --- if the one
-that comes with the operating system doesn't do exactly what you want,
-or doesn't work on your machine, you're screwed.
-
-While we may not be able to fix this problem in existing commercial
-operating systems, it shouldn't be too difficult for a few people in the
-free operating system communities to put their heads together and solve
-this problem for the popular free operating systems. That's what this
-specification aims for. Basically, it specifies an interface between a
-boot loader and a operating system, such that any complying boot loader
-should be able to load any complying operating system. This
-specification does @emph{not} specify how boot loaders should work ---
-only how they must interface with the operating system being loaded.
-
-
-@node Architecture
-@section The target architecture
-
-This specification is primarily targeted at @sc{pc}, since they are the
-most common and have the largest variety of operating systems and boot
-loaders. However, to the extent that certain other architectures may
-need a boot specification and do not have one already, a variation of
-this specification, stripped of the x86-specific details, could be
-adopted for them as well.
-
-
-@node Operating systems
-@section The target operating systems
-
-This specification is targeted toward free 32-bit operating systems
-that can be fairly easily modified to support the specification without
-going through lots of bureaucratic rigmarole. The particular free
-operating systems that this specification is being primarily designed
-for are Linux, FreeBSD, NetBSD, Mach, and VSTa. It is hoped that other
-emerging free operating systems will adopt it from the start, and thus
-immediately be able to take advantage of existing boot loaders. It would
-be nice if commercial operating system vendors eventually adopted this
-specification as well, but that's probably a pipe dream.
-
-
-@node Boot sources
-@section Boot sources
-
-It should be possible to write compliant boot loaders that load the OS
-image from a variety of sources, including floppy disk, hard disk, and
-across a network.
-
-Disk-based boot loaders may use a variety of techniques to find the
-relevant OS image and boot module data on disk, such as by
-interpretation of specific file systems (e.g. the BSD/Mach boot loader),
-using precalculated @dfn{blocklists} (e.g. LILO), loading from a
-special @dfn{boot partition} (e.g. OS/2), or even loading from within
-another operating system (e.g. the VSTa boot code, which loads from
-DOS). Similarly, network-based boot loaders could use a variety of
-network hardware and protocols.
-
-It is hoped that boot loaders will be created that support multiple
-loading mechanisms, increasing their portability, robustness, and
-user-friendliness.
-
-
-@node Boot-time configuration
-@section Configure an operating system at boot-time
-
-It is often necessary for one reason or another for the user to be able
-to provide some configuration information to an operating system
-dynamically at boot time. While this specification should not dictate
-how this configuration information is obtained by the boot loader, it
-should provide a standard means for the boot loader to pass such
-information to the operating system.
-
-
-@node Convenience to operating systems
-@section How to make OS development easier
-
-OS images should be easy to generate. Ideally, an OS image should simply
-be an ordinary 32-bit executable file in whatever file format the
-operating system normally uses. It should be possible to @code{nm} or
-disassemble OS images just like normal executables. Specialized tools
-should not be required to create OS images in a @emph{special} file
-format. If this means shifting some work from the operating system to
-a boot loader, that is probably appropriate, because all the memory
-consumed by the boot loader will typically be made available again after
-the boot process is created, whereas every bit of code in the OS image
-typically has to remain in memory forever. The operating system should
-not have to worry about getting into 32-bit mode initially, because mode
-switching code generally needs to be in the boot loader anyway in order
-to load operating system data above the 1MB boundary, and forcing the
-operating system to do this makes creation of OS images much more
-difficult.
-
-Unfortunately, there is a horrendous variety of executable file formats
-even among free Unix-like @sc{pc}-based operating systems --- generally
-a different format for each operating system. Most of the relevant free
-operating systems use some variant of a.out format, but some are moving
-to @sc{elf}. It is highly desirable for boot loaders not to have to be
-able to interpret all the different types of executable file formats in
-existence in order to load the OS image --- otherwise the boot loader
-effectively becomes operating system specific again.
-
-This specification adopts a compromise solution to this
-problem. Multiboot-compliant OS images always contain a magic
-@dfn{Multiboot header} (@pxref{OS image format}), which allows the boot
-loader to load the image without having to understand numerous a.out
-variants or other executable formats. This magic header does not need to
-be at the very beginning of the executable file, so kernel images can
-still conform to the local a.out format variant in addition to being
-Multiboot-compliant.
-
-
-@node Boot modules
-@section Boot modules
-
-Many modern operating system kernels, such as those of VSTa and Mach, do
-not by themselves contain enough mechanism to get the system fully
-operational: they require the presence of additional software modules at
-boot time in order to access devices, mount file systems, etc. While
-these additional modules could be embedded in the main OS image along
-with the kernel itself, and the resulting image be split apart manually
-by the operating system when it receives control, it is often more
-flexible, more space-efficient, and more convenient to the operating
-system and user if the boot loader can load these additional modules
-independently in the first place.
-
-Thus, this specification should provide a standard method for a boot
-loader to indicate to the operating system what auxiliary boot modules
-were loaded, and where they can be found. Boot loaders don't have to
-support multiple boot modules, but they are strongly encouraged to,
-because some operating systems will be unable to boot without them.
-
-
-@node Terminology
-@chapter The definitions of terms used through the specification
-
-@table @dfn
-@item must
-We use the term @dfn{must}, when any boot loader or OS image needs to
-follow a rule --- otherwise, the boot loader or OS image is @emph{not}
-Multiboot-compliant.
-
-@item should
-We use the term @dfn{should}, when any boot loader or OS image is
-recommended to follow a rule, but it doesn't need to follow the rule.
-
-@item may
-We use the term @dfn{may}, when any boot loader or OS image is allowed
-to follow a rule.
-
-@item boot loader
-Whatever program or set of programs loads the image of the final
-operating system to be run on the machine. The boot loader may itself
-consist of several stages, but that is an implementation detail not
-relevant to this specification. Only the @emph{final} stage of the boot
-loader --- the stage that eventually transfers control to an operating
-system --- must follow the rules specified in this document in order
-to be @dfn{Multiboot-compliant}; earlier boot loader stages may be
-designed in whatever way is most convenient.
-
-@item OS image
-The initial binary image that a boot loader loads into memory and
-transfers control to start an operating system. The OS image is
-typically an executable containing the operating system kernel.
-
-@item boot module
-Other auxiliary files that a boot loader loads into memory along with
-an OS image, but does not interpret in any way other than passing their
-locations to the operating system when it is invoked.
-
-@item Multiboot-compliant
-A boot loader or an OS image which follows the rules defined as
-@dfn{must} is Multiboot-compliant. When this specification specifies a
-rule as @dfn{should} or @dfn{may}, a Multiboot-complaint boot loader/OS
-image doesn't need to follow the rule.
-
-@item u8
-The type of unsigned 8-bit data.
-
-@item u16
-The type of unsigned 16-bit data. Because the target architecture is
-little-endian, u16 is coded in little-endian.
-
-@item u32
-The type of unsigned 32-bit data. Because the target architecture is
-little-endian, u32 is coded in little-endian.
-
-@item u64
-The type of unsigned 64-bit data. Because the target architecture is
-little-endian, u64 is coded in little-endian.
-@end table
-
-
-@node Specification
-@chapter The exact definitions of Multiboot Specification
-
-There are three main aspects of a boot loader/OS image interface:
-
-@enumerate
-@item
-The format of an OS image as seen by a boot loader.
-
-@item
-The state of a machine when a boot loader starts an operating
-system.
-
-@item
-The format of information passed by a boot loader to an operating
-system.
-@end enumerate
-
-@menu
-* OS image format::
-* Machine state::
-* Boot information format::
-@end menu
-
-
-@node OS image format
-@section OS image format
-
-An OS image may be an ordinary 32-bit executable file in the standard
-format for that particular operating system, except that it may be
-linked at a non-default load address to avoid loading on top of the
-@sc{pc}'s I/O region or other reserved areas, and of course it should
-not use shared libraries or other fancy features.
-
-An OS image must contain an additional header called @dfn{Multiboot
-header}, besides the headers of the format used by the OS image. The
-Multiboot header must be contained completely within the first 8192
-bytes of the OS image, and must be longword (32-bit) aligned. In
-general, it should come @emph{as early as possible}, and may be
-embedded in the beginning of the text segment after the @emph{real}
-executable header.
-
-@menu
-* Header layout:: The layout of Multiboot header
-* Header magic fields:: The magic fields of Multiboot header
-* Header address fields::
-* Header graphics fields::
-@end menu
-
-
-@node Header layout
-@subsection The layout of Multiboot header
-
-The layout of the Multiboot header must be as follows:
-
-@multitable @columnfractions .1 .1 .2 .5
-@item Offset @tab Type @tab Field Name @tab Note
-@item 0 @tab u32 @tab magic @tab required
-@item 4 @tab u32 @tab flags @tab required
-@item 8 @tab u32 @tab checksum @tab required
-@item 12 @tab u32 @tab header_addr @tab if flags[16] is set
-@item 16 @tab u32 @tab load_addr @tab if flags[16] is set
-@item 20 @tab u32 @tab load_end_addr @tab if flags[16] is set
-@item 24 @tab u32 @tab bss_end_addr @tab if flags[16] is set
-@item 28 @tab u32 @tab entry_addr @tab if flags[16] is set
-@item 32 @tab u32 @tab mode_type @tab if flags[2] is set
-@item 36 @tab u32 @tab width @tab if flags[2] is set
-@item 40 @tab u32 @tab height @tab if flags[2] is set
-@item 44 @tab u32 @tab depth @tab if flags[2] is set
-@end multitable
-
-The fields @samp{magic}, @samp{flags} and @samp{checksum} are defined in
-@ref{Header magic fields}, the fields @samp{header_addr},
-@samp{load_addr}, @samp{load_end_addr}, @samp{bss_end_addr} and
-@samp{entry_addr} are defined in @ref{Header address fields}, and the
-fields @samp{mode_type}, @samp{width}, @samp{height} and @samp{depth} are
-defined in @ref{Header graphics fields}.
-
-
-@node Header magic fields
-@subsection The magic fields of Multiboot header
-
-@table @samp
-@item magic
-The field @samp{magic} is the magic number identifying the header,
-which must be the hexadecimal value @code{0x1BADB002}.
-
-@item flags
-The field @samp{flags} specifies features that the OS image requests or
-requires of an boot loader. Bits 0-15 indicate requirements; if the
-boot loader sees any of these bits set but doesn't understand the flag
-or can't fulfill the requirements it indicates for some reason, it must
-notify the user and fail to load the OS image. Bits 16-31 indicate
-optional features; if any bits in this range are set but the boot loader
-doesn't understand them, it may simply ignore them and proceed as
-usual. Naturally, all as-yet-undefined bits in the @samp{flags} word
-must be set to zero in OS images. This way, the @samp{flags} fields
-serves for version control as well as simple feature selection.
-
-If bit 0 in the @samp{flags} word is set, then all boot modules loaded
-along with the operating system must be aligned on page (4KB)
-boundaries. Some operating systems expect to be able to map the pages
-containing boot modules directly into a paged address space during
-startup, and thus need the boot modules to be page-aligned.
-
-If bit 1 in the @samp{flags} word is set, then information on available
-memory via at least the @samp{mem_*} fields of the Multiboot information
-structure (@pxref{Boot information format}) must be included. If the
-boot loader is capable of passing a memory map (the @samp{mmap_*} fields)
-and one exists, then it may be included as well.
-
-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 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
-where to load the OS image. This information does not need to be
-provided if the kernel image is in @sc{elf} format, but it @emph{must}
-be provided if the images is in a.out format or in some other
-format. Compliant boot loaders must be able to load images that either
-are in @sc{elf} format or contain the load address information embedded
-in the Multiboot header; they may also directly support other executable
-formats, such as particular a.out variants, but are not required to.
-
-@item checksum
-The field @samp{checksum} is a 32-bit unsigned value which, when added
-to the other magic fields (i.e. @samp{magic} and @samp{flags}), must
-have a 32-bit unsigned sum of zero.
-@end table
-
-
-@node Header address fields
-@subsection The address fields of Multiboot header
-
-All of the address fields enabled by flag bit 16 are physical addresses.
-The meaning of each is as follows:
-
-@table @code
-@item header_addr
-Contains the address corresponding to the beginning of the Multiboot
-header --- the physical memory location at which the magic value is
-supposed to be loaded. This field serves to @dfn{synchronize} the
-mapping between OS image offsets and physical memory addresses.
-
-@item load_addr
-Contains the physical address of the beginning of the text segment. The
-offset in the OS image file at which to start loading is defined by the
-offset at which the header was found, minus (header_addr -
-load_addr). load_addr must be less than or equal to header_addr.
-
-@item load_end_addr
-Contains the physical address of the end of the data
-segment. (load_end_addr - load_addr) specifies how much data to load.
-This implies that the text and data segments must be consecutive in the
-OS image; this is true for existing a.out executable formats.
-If this field is zero, the boot loader assumes that the text and data
-segments occupy the whole OS image file.
-
-@item bss_end_addr
-Contains the physical address of the end of the bss segment. The boot
-loader initializes this area to zero, and reserves the memory it
-occupies to avoid placing boot modules and other data relevant to the
-operating system in that area. If this field is zero, the boot loader
-assumes that no bss segment is present.
-
-@item entry_addr
-The physical address to which the boot loader should jump in order to
-start running the operating system.
-@end table
-
-
-@node Header graphics fields
-@subsection The graphics fields of Multiboot header
-
-All of the graphics fields are enabled by flag bit 2. They specify the
-preferred graphics mode. Note that that is only a @emph{recommended}
-mode by the OS image. If the mode exists, the boot loader should set
-it, when the user doesn't specify a mode explicitly. Otherwise, the
-boot loader should fall back to a similar mode, if available.
-
-The meaning of each is as follows:
-
-@table @code
-@item mode_type
-Contains @samp{0} for linear graphics mode or @samp{1} for
-EGA-standard text mode. Everything else is reserved for future
-expansion. Note that the boot loader may set a text mode, even if this
-field contains @samp{0}.
-
-@item width
-Contains the number of the columns. This is specified in pixels in a
-graphics mode, and in characters in a text mode. The value zero
-indicates that the OS image has no preference.
-
-@item height
-Contains the number of the lines. This is specified in pixels in a
-graphics mode, and in characters in a text mode. The value zero
-indicates that the OS image has no preference.
-
-@item depth
-Contains the number of bits per pixel in a graphics mode, and zero in
-a text mode. The value zero indicates that the OS image has no
-preference.
-@end table
-
-
-@node Machine state
-@section Machine state
-
-When the boot loader invokes the 32-bit operating system, the machine
-must have the following state:
-
-@table @samp
-@item EAX
-Must contain the magic value @samp{0x2BADB002}; 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).
-
-@item EBX
-Must contain the 32-bit physical address of the Multiboot
-information structure provided by the boot loader (@pxref{Boot
-information format}).
-
-@item CS
-Must be a 32-bit read/execute code segment with an offset of @samp{0}
-and a limit of @samp{0xFFFFFFFF}. The exact value is undefined.
-
-@item DS
-@itemx ES
-@itemx FS
-@itemx GS
-@itemx SS
-Must be a 32-bit read/write data segment with an offset of @samp{0}
-and a limit of @samp{0xFFFFFFFF}. The exact values are all undefined.
-
-@item A20 gate
-Must be enabled.
-
-@item CR0
-Bit 31 (PG) must be cleared. Bit 0 (PE) must be set. Other bits are
-all undefined.
-
-@item EFLAGS
-Bit 17 (VM) must be cleared. Bit 9 (IF) must be cleared. Other bits
-are all undefined.
-@end table
-
-All other processor registers and flag bits are undefined. This
-includes, in particular:
-
-@table @samp
-@item ESP
-The OS image must create its own stack as soon as it needs one.
-
-@item GDTR
-Even though the segment registers are set up as described above, the
-@samp{GDTR} may be invalid, so the OS image must not load any segment
-registers (even just reloading the same values!) until it sets up its
-own @samp{GDT}.
-
-@item IDTR
-The OS image must leave interrupts disabled until it sets up its own
-@code{IDT}.
-@end table
-
-However, other machine state should be left by the boot loader in
-@dfn{normal working order}, i.e. as initialized by the @sc{bios} (or
-DOS, if that's what the boot loader runs from). In other words, the
-operating system should be able to make @sc{bios} calls and such after
-being loaded, as long as it does not overwrite the @sc{bios} data
-structures before doing so. Also, the boot loader must leave the
-@sc{pic} programmed with the normal @sc{bios}/DOS values, even if it
-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''.
-
-Upon entry to the operating system, the @code{EBX} register contains the
-physical address of a @dfn{Multiboot information} data structure,
-through which the boot loader communicates vital information to the
-operating system. The operating system can use or ignore any parts of
-the structure as it chooses; all information passed by the boot loader
-is advisory only.
-
-The Multiboot information structure and its related substructures may be
-placed anywhere in memory by the boot loader (with the exception of the
-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.
-
-The format of the Multiboot information structure (as defined so far)
-follows:
-
-@example
-@group
- +-------------------+
-0 | flags | (required)
- +-------------------+
-4 | mem_lower | (present if flags[0] is set)
-8 | mem_upper | (present if flags[0] is set)
- +-------------------+
-12 | boot_device | (present if flags[1] is set)
- +-------------------+
-16 | cmdline | (present if flags[2] is set)
- +-------------------+
-20 | mods_count | (present if flags[3] is set)
-24 | mods_addr | (present if flags[3] is set)
- +-------------------+
-28 - 40 | syms | (present if flags[4] or
- | | flags[5] is set)
- +-------------------+
-44 | mmap_length | (present if flags[6] is set)
-48 | mmap_addr | (present if flags[6] is set)
- +-------------------+
-52 | drives_length | (present if flags[7] is set)
-56 | drives_addr | (present if flags[7] is set)
- +-------------------+
-60 | config_table | (present if flags[8] is set)
- +-------------------+
-64 | boot_loader_name | (present if flags[9] is set)
- +-------------------+
-68 | apm_table | (present if flags[10] is set)
- +-------------------+
-72 | vbe_control_info | (present if flags[11] is set)
-76 | vbe_mode_info |
-80 | vbe_mode |
-82 | vbe_interface_seg |
-84 | vbe_interface_off |
-86 | vbe_interface_len |
- +-------------------+
-@end group
-@end example
-
-The first longword indicates the presence and validity of other fields
-in the Multiboot information structure. All as-yet-undefined bits must
-be set to zero by the boot loader. Any set bits that the operating
-system does not understand should be ignored. Thus, the @samp{flags}
-field also functions as a version indicator, allowing the Multiboot
-information structure to be expanded in the future without breaking
-anything.
-
-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
-at address 0, and upper memory starts at address 1 megabyte. The maximum
-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.
-
-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
-@sc{bios} disk, then this field must not be present (bit 3 must be
-clear). The operating system may use this field as a hint for
-determining its own @dfn{root} device, but is not required to. The
-@samp{boot_device} field is laid out in four one-byte subfields as
-follows:
-
-@example
-@group
-+-------+-------+-------+-------+
-| part3 | part2 | part1 | drive |
-+-------+-------+-------+-------+
-@end group
-@end example
-
-The first byte contains the @sc{bios} drive number as understood by the
-@sc{bios} INT 0x13 low-level disk interface: e.g. 0x00 for the first
-floppy disk or 0x80 for the first hard disk.
-
-The three remaining bytes specify the boot partition. @samp{part1}
-specifies the @dfn{top-level} partition number, @samp{part2} specifies a
-@dfn{sub-partition} in the top-level partition, etc. Partition numbers
-always start from zero. Unused partition bytes must be set to 0xFF. For
-example, if the disk is partitioned using a simple one-level DOS
-partitioning scheme, then @samp{part1} contains the DOS partition
-number, and @samp{part2} and @samp{part3} are both 0xFF. As another
-example, if a disk is partitioned first into DOS partitions, and then
-one of those DOS partitions is subdivided into several BSD partitions
-using BSD's @dfn{disklabel} strategy, then @samp{part1} contains the DOS
-partition number, @samp{part2} contains the BSD sub-partition within
-that DOS partition, and @samp{part3} is 0xFF.
-
-DOS extended partitions are indicated as partition numbers starting from
-4 and increasing, rather than as nested sub-partitions, even though the
-underlying disk layout of extended partitions is hierarchical in
-nature. For example, if the boot loader boots from the second extended
-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.
-
-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.
-
-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 number of modules loaded; @samp{mods_addr} contains the physical
-address of the first module structure. @samp{mods_count} may be zero,
-indicating no boot modules were loaded, even if bit 1 of @samp{flags} is
-set. Each module structure is formatted as follows:
-
-@example
-@group
- +-------------------+
-0 | mod_start |
-4 | mod_end |
- +-------------------+
-8 | string |
- +-------------------+
-12 | reserved (0) |
- +-------------------+
-@end group
-@end example
-
-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
-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
-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.
-
-@strong{Caution:} Bits 4 & 5 are mutually exclusive.
-
-If bit 4 in the @samp{flags} word is set, then the following fields in
-the Multiboot information structure starting at byte 28 are valid:
-
-@example
-@group
- +-------------------+
-28 | tabsize |
-32 | strsize |
-36 | addr |
-40 | reserved (0) |
- +-------------------+
-@end group
-@end example
-
-These indicate where the symbol table from an a.out kernel image can be
-found. @samp{addr} is the physical address of the size (4-byte unsigned
-long) of an array of a.out format @dfn{nlist} structures, followed
-immediately by the array itself, then the size (4-byte unsigned long) of
-a set of zero-terminated @sc{ascii} strings (plus sizeof(unsigned long) in
-this case), and finally the set of strings itself. @samp{tabsize} is
-equal to its size parameter (found at the beginning of the symbol
-section), and @samp{strsize} is equal to its size parameter (found at
-the beginning of the string section) of the following string table to
-which the symbol table refers. Note that @samp{tabsize} may be 0,
-indicating no symbols, even if bit 4 in the @samp{flags} word is set.
-
-If bit 5 in the @samp{flags} word is set, then the following fields in
-the Multiboot information structure starting at byte 28 are valid:
-
-@example
-@group
- +-------------------+
-28 | num |
-32 | size |
-36 | addr |
-40 | shndx |
- +-------------------+
-@end group
-@end example
-
-These indicate where the section header table from an ELF kernel is, the
-size of each entry, number of entries, and the string table used as the
-index of names. They correspond to the @samp{shdr_*} entries
-(@samp{shdr_num}, etc.) in the Executable and Linkable Format (@sc{elf})
-specification in the program header. All sections are loaded, and the
-physical address fields of the @sc{elf} section header then refer to where
-the sections are in memory (refer to the i386 @sc{elf} documentation for
-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.
-
-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 address, and @samp{mmap_length} is the total size of the buffer. The
-buffer consists of one or more of the following size/structure pairs
-(@samp{size} is really used for skipping to the next pair):
-
-@example
-@group
- +-------------------+
--4 | size |
- +-------------------+
-0 | base_addr_low |
-4 | base_addr_high |
-8 | length_low |
-12 | length_high |
-16 | type |
- +-------------------+
-@end group
-@end example
-
-where @samp{size} is the size of the associated structure in bytes, which
-can be greater than the minimum of 20 bytes. @samp{base_addr_low} is the
-lower 32 bits of the starting address, and @samp{base_addr_high} is the
-upper 32 bits, for a total of a 64-bit starting address. @samp{length_low}
-is the lower 32 bits of the size of the memory region in bytes, and
-@samp{length_high} is the upper 32 bits, for a total of a 64-bit
-length. @samp{type} is the variety of address range represented, where a
-value of 1 indicates available @sc{ram}, and all other values currently
-indicated a reserved area.
-
-The map provided is guaranteed to list all standard @sc{ram} that should
-be available for normal use.
-
-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}
-is the address, and @samp{drives_length} is the total size of drive
-structures. Note that @samp{drives_length} may be zero. Each drive
-structure is formatted as follows:
-
-@example
-@group
- +-------------------+
-0 | size |
- +-------------------+
-4 | drive_number |
- +-------------------+
-5 | drive_mode |
- +-------------------+
-6 | drive_cylinders |
-8 | drive_heads |
-9 | drive_sectors |
- +-------------------+
-10 - xx | drive_ports |
- +-------------------+
-@end group
-@end example
-
-The @samp{size} field specifies the size of this structure. The size
-varies, depending on the number of ports. Note that the size may not be
-equal to (10 + 2 * the number of ports), because of an alignment.
-
-The @samp{drive_number} field contains the BIOS drive number. The
-@samp{drive_mode} field represents the access mode used by the boot
-loader. Currently, the following modes are defined:
-
-@table @samp
-@item 0
-CHS mode (traditional cylinder/head/sector addressing mode).
-
-@item 1
-LBA mode (Logical Block Addressing mode).
-@end table
-
-The three fields, @samp{drive_cylinders}, @samp{drive_heads} and
-@samp{drive_sectors}, indicate the geometry of the drive detected by the
-@sc{bios}. @samp{drive_cylinders} contains the number of the
-cylinders. @samp{drive_heads} contains the number of the
-heads. @samp{drive_sectors} contains the number of the sectors per
-track.
-
-The @samp{drive_ports} field contains the array of the I/O ports used
-for the drive in the @sc{bios} code. The array consists of zero or more
-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).
-
-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}.
-
-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.
-
-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:
-
-@example
-@group
- +----------------------+
-0 | version |
-2 | cseg |
-4 | offset |
-8 | cseg_16 |
-10 | dseg |
-12 | flags |
-14 | cseg_len |
-16 | cseg_16_len |
-18 | dseg_len |
- +----------------------+
-@end group
-@end example
-
-The fields @samp{version}, @samp{cseg}, @samp{offset}, @samp{cseg_16},
-@samp{dseg}, @samp{flags}, @samp{cseg_len}, @samp{cseg_16_len},
-@samp{dseg_len} indicate the version number, the protected mode 32-bit
-code segment, the offset of the entry point, the protected mode 16-bit
-code segment, the protected mode 16-bit data segment, the flags, the
-length of the protected mode 32-bit code segment, the length of the
-protected mode 16-bit code segment, and the length of the protected mode
-16-bit data segment, respectively. Only the field @samp{offset} is 4
-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.
-
-If bit 11 in the @samp{flags} is set, the graphics table is available.
-This must only be done if the kernel has indicated in the
-@samp{Multiboot Header} that it accepts a graphics mode.
-
-The fields @samp{vbe_control_info} and @samp{vbe_mode_info} contain
-the physical addresses of @sc{vbe} control information returned by the
-@sc{vbe} Function 00h and @sc{vbe} mode information returned by the
-@sc{vbe} Function 01h, respectively.
-
-The field @samp{vbe_mode} indicates current video mode in the format
-specified in @sc{vbe} 3.0.
-
-The rest fields @samp{vbe_interface_seg}, @samp{vbe_interface_off}, and
-@samp{vbe_interface_len} contain the table of a protected mode interface
-defined in @sc{vbe} 2.0+. If this information is not available, those
-fields contain zero. Note that @sc{vbe} 3.0 defines another protected
-mode interface which is incompatible with the old one. If you want to
-use the new protected mode interface, you will have to find the table
-yourself.
-
-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.
-
-
-@node Examples
-@chapter Examples
-
-@strong{Caution:} The following items are not part of the specification
-document, but are included for prospective operating system and boot
-loader writers.
-
-@menu
-* Notes on PC::
-* BIOS device mapping techniques::
-* Example OS code::
-* Example boot loader code::
-@end menu
-
-
-@node Notes on PC
-@section Notes on PC
-
-In reference to bit 0 of the @samp{flags} parameter in the Multiboot
-information structure, if the bootloader in question uses older
-@sc{bios} interfaces, or the newest ones are not available (see
-description about bit 6), then a maximum of either 15 or 63 megabytes of
-memory may be reported. It is @emph{highly} recommended that boot
-loaders perform a thorough memory probe.
-
-In reference to bit 1 of the @samp{flags} parameter in the Multiboot
-information structure, it is recognized that determination of which
-@sc{bios} drive maps to which device driver in an operating system is
-non-trivial, at best. Many kludges have been made to various operating
-systems instead of solving this problem, most of them breaking under
-many conditions. To encourage the use of general-purpose solutions to
-this problem, there are 2 @sc{bios} device mapping techniques
-(@pxref{BIOS device mapping techniques}).
-
-In reference to bit 6 of the @samp{flags} parameter in the Multiboot
-information structure, it is important to note that the data structure
-used there (starting with @samp{BaseAddrLow}) is the data returned by
-the INT 15h, AX=E820h --- Query System Address Map call. See @xref{Query
-System Address Map, , Query System Address Map, grub.info, The GRUB
-Manual}, for more information. The interface here is meant to allow a
-boot loader to work unmodified with any reasonable extensions of the
-@sc{bios} interface, passing along any extra data to be interpreted by
-the operating system as desired.
-
-
-@node BIOS device mapping techniques
-@section BIOS device mapping techniques
-
-Both of these techniques should be usable from any PC operating system,
-and neither require any special support in the drivers themselves. This
-section will be flushed out into detailed explanations, particularly for
-the I/O restriction technique.
-
-The general rule is that the data comparison technique is the quick and
-dirty solution. It works most of the time, but doesn't cover all the
-bases, and is relatively simple.
-
-The I/O restriction technique is much more complex, but it has potential
-to solve the problem under all conditions, plus allow access of the
-remaining @sc{bios} devices when not all of them have operating system
-drivers.
-
-@menu
-* Data comparison technique::
-* I/O restriction technique::
-@end menu
-
-
-@node Data comparison technique
-@subsection Data comparison technique
-
-Before activating @emph{any} of the device drivers, gather enough data
-from similar sectors on each of the disks such that each one can be
-uniquely identified.
-
-After activating the device drivers, compare data from the drives using
-the operating system drivers. This should hopefully be sufficient to
-provide such a mapping.
-
-Problems:
-
-@enumerate
-@item
-The data on some @sc{bios} devices might be identical (so the part
-reading the drives from the @sc{bios} should have some mechanism to give
-up).
-
-@item
-There might be extra drives not accessible from the @sc{bios} which are
-identical to some drive used by the @sc{bios} (so it should be capable
-of giving up there as well).
-@end enumerate
-
-
-@node I/O restriction technique
-@subsection I/O restriction technique
-
-This first step may be unnecessary, but first create copy-on-write
-mappings for the device drivers writing into @sc{pc} @sc{ram}. Keep the
-original copies for the @dfn{clean @sc{bios} virtual machine} to be
-created later.
-
-For each device driver brought online, determine which @sc{bios} devices
-become inaccessible by:
-
-@enumerate
-@item
-Create a @dfn{clean @sc{bios} virtual machine}.
-
-@item
-Set the I/O permission map for the I/O area claimed by the device driver
-to no permissions (neither read nor write).
-
-@item
-Access each device.
-
-@item
-Record which devices succeed, and those which try to access the
-@dfn{restricted} I/O areas (hopefully, this will be an @dfn{xor}
-situation).
-@end enumerate
-
-For each device driver, given how many of the @sc{bios} devices were
-subsumed by it (there should be no gaps in this list), it should be easy
-to determine which devices on the controller these are.
-
-In general, you have at most 2 disks from each controller given
-@sc{bios} numbers, but they pretty much always count from the lowest
-logically numbered devices on the controller.
-
-
-@node Example OS code
-@section Example OS code
-
-In this distribution, the example Multiboot kernel @file{kernel} is
-included. The kernel just prints out the Multiboot information structure
-on the screen, so you can make use of the kernel to test a
-Multiboot-compliant boot loader and for reference to how to implement a
-Multiboot kernel. The source files can be found under the directory
-@file{docs} in the GRUB distribution.
-
-The kernel @file{kernel} consists of only three files: @file{boot.S},
-@file{kernel.c} and @file{multiboot.h}. The assembly source
-@file{boot.S} is written in GAS (@pxref{Top, , GNU assembler, as.info,
-The GNU assembler}), and contains the Multiboot information structure to
-comply with the specification. When a Multiboot-compliant boot loader
-loads and execute it, it initialize the stack pointer and @code{EFLAGS},
-and then call the function @code{cmain} defined in @file{kernel.c}. If
-@code{cmain} returns to the callee, then it shows a message to inform
-the user of the halt state and stops forever until you push the reset
-key. The file @file{kernel.c} contains the function @code{cmain},
-which checks if the magic number passed by the boot loader is valid and
-so on, and some functions to print messages on the screen. The file
-@file{multiboot.h} defines some macros, such as the magic number for the
-Multiboot header, the Multiboot header structure and the Multiboot
-information structure.
-
-@menu
-* multiboot.h::
-* boot.S::
-* kernel.c::
-* Other Multiboot kernels::
-@end menu
-
-
-@node multiboot.h
-@subsection multiboot.h
-
-This is the source code in the file @file{multiboot.h}:
-
-@example
-@include multiboot.h.texi
-@end example
-
-
-@node boot.S
-@subsection boot.S
-
-In the file @file{boot.S}:
-
-@example
-@include boot.S.texi
-@end example
-
-
-@node kernel.c
-@subsection kernel.c
-
-And, in the file @file{kernel.c}:
-
-@example
-@include kernel.c.texi
-@end example
-
-
-@node Other Multiboot kernels
-@subsection Other Multiboot kernels
-
-Other useful information should be available in Multiboot kernels, such
-as GNU Mach and Fiasco @url{http://os.inf.tu-dresden.de/fiasco/}. And,
-it is worth mentioning the OSKit
-@url{http://www.cs.utah.edu/projects/flux/oskit/}, which provides a
-library supporting the specification.
-
-
-@node Example boot loader code
-@section Example boot loader code
-
-The GNU GRUB (@pxref{Top, , GRUB, grub.info, The GRUB manual}) project
-is a full Multiboot-compliant boot loader, supporting all required and
-optional features present in this specification. A public release has
-not been made, but the test release is available from:
-
-@url{ftp://alpha.gnu.org/gnu/grub}
-
-See the webpage @url{http://www.gnu.org/software/grub/grub.html}, for
-more information.
-
-
-@node History
-@chapter The change log of this specification
-
-@table @asis
-@item 0.7
-@itemize @bullet
-@item
-@dfn{Multiboot Standard} is renamed to @dfn{Multiboot Specification}.
-
-@item
-Graphics fields are added to Multiboot header.
-
-@item
-BIOS drive information, BIOS configuration table, the name of a boot
-loader, APM information, and graphics information are added to Multiboot
-information.
-
-@item
-Rewritten in Texinfo format.
-
-@item
-Rewritten, using more strict words.
-
-@item
-The maintainer changes to the GNU GRUB maintainer team
-@email{bug-grub@@gnu.org}, from Bryan Ford and Erich Stefan Boleyn.
-
-@item
-The byte order of the @samp{boot_device} in Multiboot information is
-reversed. This was a mistake.
-
-@item
-The offset of the address fields were wrong.
-
-@item
-The format is adapted to a newer Texinfo, and the version number is
-specified more explicitly in the title.
-@end itemize
-
-@item 0.6
-@itemize @bullet
-@item
-A few wording changes.
-
-@item
-Header checksum.
-
-@item
-Classification of machine state passed to an operating system.
-@end itemize
-
-@item 0.5
-@itemize @bullet
-@item
-Name change.
-@end itemize
-
-@item 0.4
-@itemize @bullet
-@item
-Major changes plus HTMLification.
-@end itemize
-@end table
-
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@contents
-@bye
projects / thirdparty / grub.git / commitdiff
