1N/A\input texinfo @c -*-texinfo-*-
1N/A@c %**start of header
1N/A@settitle Multiboot Specification
1N/A@c Unify all our little indices for now.
1N/A@footnotestyle separate
1N/A* Multiboot Specification: (multiboot). Multiboot Specification.
1N/ACopyright @copyright{} 1995, 96 Erich Stefan Boleyn <erich@@
uruk.org>
1N/ACopyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
1N/APermission is granted to make and distribute verbatim copies of
1N/Athis manual provided the copyright notice and this permission notice
1N/Aare preserved on all copies.
1N/APermission is granted to process this file through TeX and print the
1N/Aresults, provided the printed document carries a copying permission
1N/Anotice identical to this one except for the removal of this paragraph
1N/A(this paragraph not being relevant to the printed manual).
1N/APermission is granted to copy and distribute modified versions of this
1N/Amanual under the conditions for verbatim copying, provided also that
1N/Athe entire resulting derived work is distributed under the terms of a
1N/Apermission notice identical to this one.
1N/APermission is granted to copy and distribute translations of this manual
1N/Ainto another language, under the above conditions for modified versions.
1N/A@title The Multiboot Specification
1N/A@author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn, Kunihiro Ishiguro
1N/A@vskip 0pt plus 1filll
1N/ACopyright @copyright{} 1995, 96 Erich Stefan Boleyn <erich@@
uruk.org>
1N/ACopyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
1N/APermission is granted to make and distribute verbatim copies of
1N/Athis manual provided the copyright notice and this permission notice
1N/Aare preserved on all copies.
1N/APermission is granted to copy and distribute modified versions of this
1N/Amanual under the conditions for verbatim copying, provided also that
1N/Athe entire resulting derived work is distributed under the terms of a
1N/Apermission notice identical to this one.
1N/APermission is granted to copy and distribute translations of this manual
1N/Ainto another language, under the above conditions for modified versions.
1N/A@top Multiboot Specification
1N/AThis file documents Multiboot Specification, the proposal for the boot
1N/Asequence standard. This edition documents version 0.6.93.
1N/A@chapter Introduction to Multiboot Specification
1N/AThis chapter describes some rough information on the Multiboot
1N/ASpecification. Note that this is not a part of the specification itself.
1N/A* Operating systems::
1N/A* Boot-time configuration::
1N/A* Convenience to operating systems::
1N/A@section The background of Multiboot Specification
1N/AEvery operating system ever created tends to have its own boot loader.
1N/AInstalling a new operating system on a machine generally involves
1N/Ainstalling a whole new set of boot mechanisms, each with completely
1N/Adifferent install-time and boot-time user interfaces. Getting multiple
1N/Aoperating systems to coexist reliably on one machine through typical
1N/A@dfn{chaining} mechanisms can be a nightmare. There is little or no
1N/Achoice of boot loaders for a particular operating system --- if the one
1N/Athat comes with the operating system doesn't do exactly what you want,
1N/Aor doesn't work on your machine, you're screwed.
1N/AWhile we may not be able to fix this problem in existing commercial
1N/Aoperating systems, it shouldn't be too difficult for a few people in the
1N/Afree operating system communities to put their heads together and solve
1N/Athis problem for the popular free operating systems. That's what this
1N/Aspecification aims for. Basically, it specifies an interface between a
1N/Aboot loader and a operating system, such that any complying boot loader
1N/Ashould be able to load any complying operating system. This
1N/Aspecification does @emph{not} specify how boot loaders should work ---
1N/Aonly how they must interface with the operating system being loaded.
1N/A@section The target architecture
1N/AThis specification is primarily targeted at @sc{pc}, since they are the
1N/Amost common and have the largest variety of operating systems and boot
1N/Aloaders. However, to the extent that certain other architectures may
1N/Aneed a boot specification and do not have one already, a variation of
1N/Athis specification, stripped of the x86-specific details, could be
1N/Aadopted for them as well.
1N/A@node Operating systems
1N/A@section The target operating systems
1N/AThis specification is targeted toward free 32-bit operating systems
1N/Athat can be fairly easily modified to support the specification without
1N/Agoing through lots of bureaucratic rigmarole. The particular free
1N/Aoperating systems that this specification is being primarily designed
1N/Afor are Linux, FreeBSD, NetBSD, Mach, and VSTa. It is hoped that other
1N/Aemerging free operating systems will adopt it from the start, and thus
1N/Aimmediately be able to take advantage of existing boot loaders. It would
1N/Abe nice if commercial operating system vendors eventually adopted this
1N/Aspecification as well, but that's probably a pipe dream.
1N/A@section Boot sources
1N/AIt should be possible to write compliant boot loaders that load the OS
1N/Aimage from a variety of sources, including floppy disk, hard disk, and
1N/ADisk-based boot loaders may use a variety of techniques to find the
1N/Arelevant OS image and boot module data on disk, such as by
1N/Ausing precalculated @dfn{block lists} (
e.g. LILO), loading from a
1N/Aspecial @dfn{boot partition} (
e.g. OS/2), or even loading from within
1N/Aanother operating system (
e.g. the VSTa boot code, which loads from
1N/ADOS). Similarly, network-based boot loaders could use a variety of
1N/Anetwork hardware and protocols.
1N/AIt is hoped that boot loaders will be created that support multiple
1N/Aloading mechanisms, increasing their portability, robustness, and
1N/A@node Boot-time configuration
1N/A@section Configure an operating system at boot-time
1N/AIt is often necessary for one reason or another for the user to be able
1N/Ato provide some configuration information to an operating system
1N/Adynamically at boot time. While this specification should not dictate
1N/Ahow this configuration information is obtained by the boot loader, it
1N/Ashould provide a standard means for the boot loader to pass such
1N/Ainformation to the operating system.
1N/A@node Convenience to operating systems
1N/A@section How to make OS development easier
1N/AOS images should be easy to generate. Ideally, an OS image should simply
1N/Abe an ordinary 32-bit executable file in whatever file format the
1N/Aoperating system normally uses. It should be possible to @code{nm} or
1N/Adisassemble OS images just like normal executables. Specialized tools
1N/Ashould not be required to create OS images in a @emph{special} file
1N/Aformat. If this means shifting some work from the operating system to
1N/Aa boot loader, that is probably appropriate, because all the memory
1N/Aconsumed by the boot loader will typically be made available again after
1N/Athe boot process is created, whereas every bit of code in the OS image
1N/Atypically has to remain in memory forever. The operating system should
1N/Anot have to worry about getting into 32-bit mode initially, because mode
1N/Aswitching code generally needs to be in the boot loader anyway in order
1N/Ato load operating system data above the 1MB boundary, and forcing the
1N/Aoperating system to do this makes creation of OS images much more
1N/AUnfortunately, there is a horrendous variety of executable file formats
1N/Aeven among free Unix-like @sc{pc}-based operating systems --- generally
1N/Aa different format for each operating system. Most of the relevant free
1N/Aoperating systems use some variant of
a.out format, but some are moving
1N/Ato @sc{elf}. It is highly desirable for boot loaders not to have to be
1N/Aable to interpret all the different types of executable file formats in
1N/Aexistence in order to load the OS image --- otherwise the boot loader
1N/Aeffectively becomes operating system specific again.
1N/AThis specification adopts a compromise solution to this
1N/Aproblem. Multiboot-compliant OS images always contain a magic
1N/A@dfn{Multiboot header} (@pxref{OS image format}), which allows the boot
1N/Aloader to load the image without having to understand numerous
a.out 1N/Avariants or other executable formats. This magic header does not need to
1N/Abe at the very beginning of the executable file, so kernel images can
1N/Astill conform to the local
a.out format variant in addition to being
1N/A@section Boot modules
1N/AMany modern operating system kernels, such as those of VSTa and Mach, do
1N/Anot by themselves contain enough mechanism to get the system fully
1N/Aoperational: they require the presence of additional software modules at
1N/Aboot time in order to access devices, mount file systems, etc. While
1N/Athese additional modules could be embedded in the main OS image along
1N/Awith the kernel itself, and the resulting image be split apart manually
1N/Aby the operating system when it receives control, it is often more
1N/Aflexible, more space-efficient, and more convenient to the operating
1N/Asystem and user if the boot loader can load these additional modules
1N/Aindependently in the first place.
1N/AThus, this specification should provide a standard method for a boot
1N/Aloader to indicate to the operating system what auxiliary boot modules
1N/Awere loaded, and where they can be found. Boot loaders don't have to
1N/Asupport multiple boot modules, but they are strongly encouraged to,
1N/Abecause some operating systems will be unable to boot without them.
1N/A@chapter The definitions of terms used through the specification
1N/AWe use the term @dfn{must}, when any boot loader or OS image needs to
1N/Afollow a rule --- otherwise, the boot loader or OS image is @emph{not}
1N/AWe use the term @dfn{should}, when any boot loader or OS image is
1N/Arecommended to follow a rule, but it doesn't need to follow the rule.
1N/AWe use the term @dfn{may}, when any boot loader or OS image is allowed
1N/AWhatever program or set of programs loads the image of the final
1N/Aoperating system to be run on the machine. The boot loader may itself
1N/Aconsist of several stages, but that is an implementation detail not
1N/Arelevant to this specification. Only the @emph{final} stage of the boot
1N/Aloader --- the stage that eventually transfers control to an operating
1N/Asystem --- must follow the rules specified in this document in order
1N/Ato be @dfn{Multiboot-compliant}; earlier boot loader stages may be
1N/Adesigned in whatever way is most convenient.
1N/AThe initial binary image that a boot loader loads into memory and
1N/Atransfers control to start an operating system. The OS image is
1N/Atypically an executable containing the operating system kernel.
1N/AOther auxiliary files that a boot loader loads into memory along with
1N/Aan OS image, but does not interpret in any way other than passing their
1N/Alocations to the operating system when it is invoked.
1N/A@item Multiboot-compliant
1N/AA boot loader or an OS image which follows the rules defined as
1N/A@dfn{must} is Multiboot-compliant. When this specification specifies a
1N/Arule as @dfn{should} or @dfn{may}, a Multiboot-complaint boot
loader/OS 1N/Aimage doesn't need to follow the rule.
1N/AThe type of unsigned 8-bit data.
1N/AThe type of unsigned 16-bit data. Because the target architecture is
1N/Alittle-endian, u16 is coded in little-endian.
1N/AThe type of unsigned 32-bit data. Because the target architecture is
1N/Alittle-endian, u32 is coded in little-endian.
1N/AThe type of unsigned 64-bit data. Because the target architecture is
1N/Alittle-endian, u64 is coded in little-endian.
1N/A@chapter The exact definitions of Multiboot Specification
1N/AThere are three main aspects of a boot
loader/OS image interface:
1N/AThe format of an OS image as seen by a boot loader.
1N/AThe state of a machine when a boot loader starts an operating
1N/AThe format of information passed by a boot loader to an operating
1N/A* Boot information format::
1N/A@node OS image format
1N/A@section OS image format
1N/AAn OS image may be an ordinary 32-bit executable file in the standard
1N/Aformat for that particular operating system, except that it may be
1N/Alinked at a non-default load address to avoid loading on top of the
1N/A@sc{pc}'s I/O region or other reserved areas, and of course it should
1N/Anot use shared libraries or other fancy features.
1N/AAn OS image must contain an additional header called @dfn{Multiboot
1N/Aheader}, besides the headers of the format used by the OS image. The
1N/AMultiboot header must be contained completely within the first 8192
1N/Abytes of the OS image, and must be longword (32-bit) aligned. In
1N/Ageneral, it should come @emph{as early as possible}, and may be
1N/Aembedded in the beginning of the text segment after the @emph{real}
1N/A* Header layout:: The layout of Multiboot header
1N/A* Header magic fields:: The magic fields of Multiboot header
1N/A* Header address fields::
1N/A* Header graphics fields::
1N/A@subsection The layout of Multiboot header
1N/AThe layout of the Multiboot header must be as follows:
1N/A@multitable @columnfractions .1 .1 .2 .5
1N/A@item Offset @tab Type @tab Field Name @tab Note
1N/A@item 0 @tab u32 @tab magic @tab required
1N/A@item 4 @tab u32 @tab flags @tab required
1N/A@item 8 @tab u32 @tab checksum @tab required
1N/A@item 12 @tab u32 @tab header_addr @tab if flags[16] is set
1N/A@item 16 @tab u32 @tab load_addr @tab if flags[16] is set
1N/A@item 20 @tab u32 @tab load_end_addr @tab if flags[16] is set
1N/A@item 24 @tab u32 @tab bss_end_addr @tab if flags[16] is set
1N/A@item 28 @tab u32 @tab entry_addr @tab if flags[16] is set
1N/A@item 32 @tab u32 @tab mode_type @tab if flags[2] is set
1N/A@item 36 @tab u32 @tab width @tab if flags[2] is set
1N/A@item 40 @tab u32 @tab height @tab if flags[2] is set
1N/A@item 44 @tab u32 @tab depth @tab if flags[2] is set
1N/AThe fields @samp{magic}, @samp{flags} and @samp{checksum} are defined in
1N/A@ref{Header magic fields}, the fields @samp{header_addr},
1N/A@samp{load_addr}, @samp{load_end_addr}, @samp{bss_end_addr} and
1N/A@samp{entry_addr} are defined in @ref{Header address fields}, and the
1N/Afields @samp{mode_type}, @samp{width}, @samp{height} and @samp{depth} are
1N/Adefind in @ref{Header graphics fields}.
1N/A@node Header magic fields
1N/A@subsection The magic fields of Multiboot header
1N/AThe field @samp{magic} is the magic number identifying the header,
1N/Awhich must be the hexadecimal value @code{0x1BADB002}.
1N/AThe field @samp{flags} specifies features that the OS image requests or
1N/Arequires of an boot loader. Bits 0-15 indicate requirements; if the
1N/Aboot loader sees any of these bits set but doesn't understand the flag
1N/Aor can't fulfill the requirements it indicates for some reason, it must
1N/Anotify the user and fail to load the OS image. Bits 16-31 indicate
1N/Aoptional features; if any bits in this range are set but the boot loader
1N/Adoesn't understand them, it may simply ignore them and proceed as
1N/Ausual. Naturally, all as-yet-undefined bits in the @samp{flags} word
1N/Amust be set to zero in OS images. This way, the @samp{flags} fields
1N/Aserves for version control as well as simple feature selection.
1N/AIf bit 0 in the @samp{flags} word is set, then all boot modules loaded
1N/Aalong with the operating system must be aligned on page (4KB)
1N/Aboundaries. Some operating systems expect to be able to map the pages
1N/Acontaining boot modules directly into a paged address space during
1N/Astartup, and thus need the boot modules to be page-aligned.
1N/AIf bit 1 in the @samp{flags} word is set, then information on available
1N/Amemory via at least the @samp{mem_*} fields of the Multiboot information
1N/Astructure (@pxref{Boot information format}) must be included. If the
1N/Aboot loader is capable of passing a memory map (the @samp{mmap_*} fields)
1N/Aand one exists, then it may be included as well.
1N/AIf bit 2 in the @samp{flags} word is set, information about the video
1N/Amode table (@pxref{Boot information format}) must be available to the
1N/AIf bit 16 in the @samp{flags} word is set, then the fields at offsets
1N/A8-24 in the Multiboot header are valid, and the boot loader should use
1N/Athem instead of the fields in the actual executable header to calculate
1N/Awhere to load the OS image. This information does not need to be
1N/Aprovided if the kernel image is in @sc{elf} format, but it @emph{must}
1N/Abe provided if the images is in
a.out format or in some other
1N/Aformat. Compliant boot loaders must be able to load images that either
1N/Aare in @sc{elf} format or contain the load address information embedded
1N/Ain the Multiboot header; they may also directly support other executable
1N/Aformats, such as particular
a.out variants, but are not required to.
1N/AThe field @samp{checksum} is a 32-bit unsigned value which, when added
1N/Ato the other magic fields (
i.e. @samp{magic} and @samp{flags}), must
1N/Ahave a 32-bit unsigned sum of zero.
1N/A@node Header address fields
1N/A@subsection The address fields of Multiboot header
1N/AAll of the address fields enabled by flag bit 16 are physical addresses.
1N/AThe meaning of each is as follows:
1N/AContains the address corresponding to the beginning of the Multiboot
1N/Aheader --- the physical memory location at which the magic value is
1N/Asupposed to be loaded. This field serves to @dfn{synchronize} the
1N/Amapping between OS image offsets and physical memory addresses.
1N/AContains the physical address of the beginning of the text segment. The
1N/Aoffset in the OS image file at which to start loading is defined by the
1N/Aoffset at which the header was found, minus (header_addr -
1N/Aload_addr). load_addr must be less than or equal to header_addr.
1N/AContains the physical address of the end of the data
1N/Asegment. (load_end_addr - load_addr) specifies how much data to load.
1N/AThis implies that the text and data segments must be consecutive in the
1N/AOS image; this is true for existing
a.out executable formats.
1N/AIf this field is zero, the boot loader assumes that the text and data
1N/Asegments occupy the whole OS image file.
1N/AContains the physical address of the end of the bss segment. The boot
1N/Aloader initializes this area to zero, and reserves the memory it
1N/Aoccupies to avoid placing boot modules and other data relevant to the
1N/Aoperating system in that area. If this field is zero, the boot loader
1N/Aassumes that no bss segment is present.
1N/AThe physical address to which the boot loader should jump in order to
1N/Astart running the operating system.
1N/A@node Header graphics fields
1N/A@subsection The graphics fields of Multiboot header
1N/AAll of the graphics fields are enabled by flag bit 2. They specify the
1N/Apreferred graphics mode. Note that that is only a @emph{recommended}
1N/Amode by the OS image. If the mode exists, the boot loader should set
1N/Ait, when the user doesn't specify a mode explicitly. Otherwise, the
1N/Aboot loader should fall back to a similar mode, if available.
1N/AThe meaning of each is as follows:
1N/AContains @samp{0} for linear graphics mode or @samp{1} for
1N/AEGA-standard text mode. Everything else is reserved for future
1N/Aexpansion. Note that the boot loader may set a text mode, even if this
1N/Afield contains @samp{0}.
1N/AContains the number of the columns. This is specified in pixels in a
1N/Agraphics mode, and in characters in a text mode. The value zero
1N/Aindicates that the OS image has no preference.
1N/AContains the number of the lines. This is specified in pixels in a
1N/Agraphics mode, and in characters in a text mode. The value zero
1N/Aindicates that the OS image has no preference.
1N/AContains the number of bits per pixel in a graphics mode, and zero in
1N/Aa text mode. The value zero indicates that the OS image has no
1N/A@section Machine state
1N/AWhen the boot loader invokes the 32-bit operating system, the machine
1N/Amust have the following state:
1N/AMust contain the magic value @samp{0x2BADB002}; the presence of this
1N/Avalue indicates to the operating system that it was loaded by a
1N/AMultiboot-compliant boot loader (
e.g. as opposed to another type of
1N/Aboot loader that the operating system can also be loaded from).
1N/AMust contain the 32-bit physical address of the Multiboot
1N/Ainformation structure provided by the boot loader (@pxref{Boot
1N/Ainformation format}).
1N/Aand a limit of @samp{0xFFFFFFFF}. The exact value is undefined.
1N/AMust be a 32-bit
read/write data segment with an offset of @samp{0}
1N/Aand a limit of @samp{0xFFFFFFFF}. The exact values are all undefined.
1N/ABit 31 (PG) must be cleared. Bit 0 (PE) must be set. Other bits are
1N/ABit 17 (VM) must be cleared. Bit 9 (IF) must be cleared. Other bits
1N/AAll other processor registers and flag bits are undefined. This
1N/Aincludes, in particular:
1N/AThe OS image must create its own stack as soon as it needs one.
1N/AEven though the segment registers are set up as described above, the
1N/A@samp{GDTR} may be invalid, so the OS image must not load any segment
1N/Aregisters (even just reloading the same values!) until it sets up its
1N/AThe OS image must leave interrupts disabled until it sets up its own
1N/AHowever, other machine state should be left by the boot loader in
1N/A@dfn{normal working order},
i.e. as initialized by the @sc{bios} (or
1N/ADOS, if that's what the boot loader runs from). In other words, the
1N/Aoperating system should be able to make @sc{bios} calls and such after
1N/Abeing loaded, as long as it does not overwrite the @sc{bios} data
1N/Astructures before doing so. Also, the boot loader must leave the
1N/A@sc{pic} programmed with the normal @sc{bios}/DOS values, even if it
1N/Achanged them during the switch to 32-bit mode.
1N/A@node Boot information format
1N/A@section Boot information format
1N/AFIXME: Split this chapter like the chapter ``OS image format''.
1N/AUpon entry to the operating system, the @code{EBX} register contains the
1N/Aphysical address of a @dfn{Multiboot information} data structure,
1N/Athrough which the boot loader communicates vital information to the
1N/Aoperating system. The operating system can use or ignore any parts of
1N/Athe structure as it chooses; all information passed by the boot loader
1N/AThe Multiboot information structure and its related substructures may be
1N/Aplaced anywhere in memory by the boot loader (with the exception of the
1N/Amemory reserved for the kernel and boot modules, of course). It is the
1N/Aoperating system's responsibility to avoid overwriting this memory until
1N/AThe format of the Multiboot information structure (as defined so far)
1N/A +-------------------+
1N/A0 | flags | (required)
1N/A +-------------------+
1N/A4 | mem_lower | (present if flags[0] is set)
1N/A8 | mem_upper | (present if flags[0] is set)
1N/A +-------------------+
1N/A12 | boot_device | (present if flags[1] is set)
1N/A +-------------------+
1N/A16 | cmdline | (present if flags[2] is set)
1N/A +-------------------+
1N/A20 | mods_count | (present if flags[3] is set)
1N/A24 | mods_addr | (present if flags[3] is set)
1N/A +-------------------+
1N/A28 - 40 | syms | (present if flags[4] or
1N/A | | flags[5] is set)
1N/A +-------------------+
1N/A44 | mmap_length | (present if flags[6] is set)
1N/A48 | mmap_addr | (present if flags[6] is set)
1N/A +-------------------+
1N/A52 | drives_length | (present if flags[7] is set)
1N/A56 | drives_addr | (present if flags[7] is set)
1N/A +-------------------+
1N/A60 | config_table | (present if flags[8] is set)
1N/A +-------------------+
1N/A64 | boot_loader_name | (present if flags[9] is set)
1N/A +-------------------+
1N/A68 | apm_table | (present if flags[10] is set)
1N/A +-------------------+
1N/A72 | vbe_control_info | (present if flags[11] is set)
1N/A82 | vbe_interface_seg |
1N/A84 | vbe_interface_off |
1N/A86 | vbe_interface_len |
1N/A +-------------------+
1N/AThe first longword indicates the presence and validity of other fields
1N/Ain the Multiboot information structure. All as-yet-undefined bits must
1N/Abe set to zero by the boot loader. Any set bits that the operating
1N/Asystem does not understand should be ignored. Thus, the @samp{flags}
1N/Afield also functions as a version indicator, allowing the Multiboot
1N/Ainformation structure to be expanded in the future without breaking
1N/AIf bit 0 in the @samp{flags} word is set, then the @samp{mem_*} fields
1N/Aare valid. @samp{mem_lower} and @samp{mem_upper} indicate the amount of
1N/Alower and upper memory, respectively, in kilobytes. Lower memory starts
1N/Aat address 0, and upper memory starts at address 1 megabyte. The maximum
1N/Apossible value for lower memory is 640 kilobytes. The value returned for
1N/Aupper memory is maximally the address of the first upper memory hole
1N/Aminus 1 megabyte. It is not guaranteed to be this value.
1N/AIf bit 1 in the @samp{flags} word is set, then the @samp{boot_device}
1N/Afield is valid, and indicates which @sc{bios} disk device the boot
1N/Aloader loaded the OS image from. If the OS image was not loaded from a
1N/A@sc{bios} disk, then this field must not be present (bit 3 must be
1N/Aclear). The operating system may use this field as a hint for
1N/Adetermining its own @dfn{root} device, but is not required to. The
1N/A@samp{boot_device} field is laid out in four one-byte subfields as
1N/A+-------+-------+-------+-------+
1N/A| drive | part1 | part2 | part3 |
1N/A+-------+-------+-------+-------+
1N/AThe first byte contains the @sc{bios} drive number as understood by the
1N/A@sc{bios} INT 0x13 low-level disk interface:
e.g. 0x00 for the first
1N/Afloppy disk or 0x80 for the first hard disk.
1N/AThe three remaining bytes specify the boot partition. @samp{part1}
1N/Aspecifies the @dfn{top-level} partition number, @samp{part2} specifies a
1N/A@dfn{sub-partition} in the top-level partition, etc. Partition numbers
1N/Aalways start from zero. Unused partition bytes must be set to 0xFF. For
1N/Aexample, if the disk is partitioned using a simple one-level DOS
1N/Apartitioning scheme, then @samp{part1} contains the DOS partition
1N/Anumber, and @samp{part2} and @samp{part3} are both 0xFF. As another
1N/Aexample, if a disk is partitioned first into DOS partitions, and then
1N/Aone of those DOS partitions is subdivided into several BSD partitions
1N/Ausing BSD's @dfn{disklabel} strategy, then @samp{part1} contains the DOS
1N/Apartition number, @samp{part2} contains the BSD sub-partition within
1N/Athat DOS partition, and @samp{part3} is 0xFF.
1N/ADOS extended partitions are indicated as partition numbers starting from
1N/A4 and increasing, rather than as nested sub-partitions, even though the
1N/Aunderlying disk layout of extended partitions is hierarchical in
1N/Anature. For example, if the boot loader boots from the second extended
1N/Apartition on a disk partitioned in conventional DOS style, then
1N/A@samp{part1} will be 5, and @samp{part2} and @samp{part3} will both be
1N/AIf bit 2 of the @samp{flags} longword is set, the @samp{cmdline} field
1N/Ais valid, and contains the physical address of the command line to
1N/Abe passed to the kernel. The command line is a normal C-style
1N/Azero-terminated string.
1N/AIf bit 3 of the @samp{flags} is set, then the @samp{mods} fields
1N/Aindicate to the kernel what boot modules were loaded along with the
1N/Akernel image, and where they can be found. @samp{mods_count} contains
1N/Athe number of modules loaded; @samp{mods_addr} contains the physical
1N/Aaddress of the first module structure. @samp{mods_count} may be zero,
1N/Aindicating no boot modules were loaded, even if bit 1 of @samp{flags} is
1N/Aset. Each module structure is formatted as follows:
1N/A +-------------------+
1N/A +-------------------+
1N/A +-------------------+
1N/A +-------------------+
1N/AThe first two fields contain the start and end addresses of the boot
1N/Amodule itself. The @samp{string} field provides an arbitrary string to
1N/Abe associated with that particular boot module; it is a zero-terminated
1N/AASCII string, just like the kernel command line. The @samp{string} field
1N/Amay be 0 if there is no string associated with the module. Typically the
1N/Astring might be a command line (
e.g. if the operating system treats boot
1N/Amodules as executable programs), or a pathname (
e.g. if the operating
1N/Asystem treats boot modules as files in a file system), but its exact use
1N/Ais specific to the operating system. The @samp{reserved} field must be
1N/Aset to 0 by the boot loader and ignored by the operating system.
1N/A@strong{Caution:} Bits 4 & 5 are mutually exclusive.
1N/AIf bit 4 in the @samp{flags} word is set, then the following fields in
1N/Athe Multiboot information structure starting at byte 28 are valid:
1N/A +-------------------+
1N/A +-------------------+
1N/AThese indicate where the symbol table from an
a.out kernel image can be
1N/Afound. @samp{addr} is the physical address of the size (4-byte unsigned
1N/Along) of an array of
a.out format @dfn{nlist} structures, followed
1N/Aimmediately by the array itself, then the size (4-byte unsigned long) of
1N/Aa set of zero-terminated @sc{ascii} strings (plus sizeof(unsigned long) in
1N/Athis case), and finally the set of strings itself. @samp{tabsize} is
1N/Aequal to its size parameter (found at the beginning of the symbol
1N/Asection), and @samp{strsize} is equal to its size parameter (found at
1N/Athe beginning of the string section) of the following string table to
1N/Awhich the symbol table refers. Note that @samp{tabsize} may be 0,
1N/Aindicating no symbols, even if bit 4 in the @samp{flags} word is set.
1N/AIf bit 5 in the @samp{flags} word is set, then the following fields in
1N/Athe Multiboot information structure starting at byte 28 are valid:
1N/A +-------------------+
1N/A +-------------------+
1N/AThese indicate where the section header table from an ELF kernel is, the
1N/Asize of each entry, number of entries, and the string table used as the
1N/Aindex of names. They correspond to the @samp{shdr_*} entries
1N/A(@samp{shdr_num}, etc.) in the Executable and Linkable Format (@sc{elf})
1N/Aspecification in the program header. All sections are loaded, and the
1N/Aphysical address fields of the @sc{elf} section header then refer to where
1N/Athe sections are in memory (refer to the i386 @sc{elf} documentation for
1N/Adetails as to how to read the section header(s)). Note that
1N/A@samp{shdr_num} may be 0, indicating no symbols, even if bit 5 in the
1N/A@samp{flags} word is set.
1N/AIf bit 6 in the @samp{flags} word is set, then the @samp{mmap_*} fields
1N/Aare valid, and indicate the address and length of a buffer containing a
1N/Amemory map of the machine provided by the @sc{bios}. @samp{mmap_addr} is
1N/Athe address, and @samp{mmap_length} is the total size of the buffer. The
1N/A(@samp{size} is really used for skipping to the next pair):
1N/A +-------------------+
1N/A +-------------------+
1N/A +-------------------+
1N/Awhere @samp{size} is the size of the associated structure in bytes, which
1N/Acan be greater than the minimum of 20 bytes. @samp{base_addr_low} is the
1N/Alower 32 bits of the starting address, and @samp{base_addr_high} is the
1N/Aupper 32 bits, for a total of a 64-bit starting address. @samp{length_low}
1N/Ais the lower 32 bits of the size of the memory region in bytes, and
1N/A@samp{length_high} is the upper 32 bits, for a total of a 64-bit
1N/Alength. @samp{type} is the variety of address range represented, where a
1N/Avalue of 1 indicates available @sc{ram}, and all other values currently
1N/Aindicated a reserved area.
1N/AThe map provided is guaranteed to list all standard @sc{ram} that should
1N/Abe available for normal use.
1N/AIf bit 7 in the @samp{flags} is set, then the @samp{drives_*} fields
1N/Aare valid, and indicate the address of the physical address of the first
1N/Adrive structure and the size of drive structures. @samp{drives_addr}
1N/Ais the address, and @samp{drives_length} is the total size of drive
1N/Astructures. Note that @samp{drives_length} may be zero. Each drive
1N/Astructure is formatted as follows:
1N/A +-------------------+
1N/A +-------------------+
1N/A +-------------------+
1N/A +-------------------+
1N/A6 | drive_cylinders |
1N/A +-------------------+
1N/A10 - xx | drive_ports |
1N/A +-------------------+
1N/AThe @samp{size} field specifies the size of this structure. The size
1N/Avaries, depending on the number of ports. Note that the size may not be
1N/Aequal to (10 + 2 * the number of ports), because of an alignment.
1N/AThe @samp{drive_number} field contains the BIOS drive number. The
1N/A@samp{drive_mode} field represents the access mode used by the boot
1N/Aloader. Currently, the following modes are defined:
1N/ALBA mode (Logical Block Addressing mode).
1N/AThe three fields, @samp{drive_cylinders}, @samp{drive_heads} and
1N/A@samp{drive_sectors}, indicate the geometry of the drive detected by the
1N/A@sc{bios}. @samp{drive_cylinders} contains the number of the
1N/Acylinders. @samp{drive_heads} contains the number of the
1N/Aheads. @samp{drive_sectors} contains the number of the sectors per
1N/AThe @samp{drive_ports} field contains the array of the I/O ports used
1N/Afor the drive in the @sc{bios} code. The array consists of zero or more
1N/Aunsigned two-bytes integers, and is terminated with zero. Note that the
1N/Aarray may contain any number of I/O ports that are not related to the
1N/Adrive actually (such as @sc{dma} controller's ports).
1N/AIf bit 8 in the @samp{flags} is set, then the @samp{config_table} field
1N/Ais valid, and indicates the address of the @sc{rom} configuration table
1N/Areturned by the @dfn{GET CONFIGURATION} @sc{bios} call. If the @sc{bios}
1N/Acall fails, then the size of the table must be @emph{zero}.
1N/AIf bit 9 in the @samp{flags} is set, the @samp{boot_loader_name} field
1N/Ais valid, and contains the physical address of the name of a boot
1N/Aloader booting the kernel. The name is a normal C-style zero-terminated
1N/AIf bit 10 in the @samp{flags} is set, the @samp{apm_table} field is
1N/Avalid, and contains the physical address of an @sc{apm} table defined as
1N/A +----------------------+
1N/A +----------------------+
1N/AThe fields @samp{version}, @samp{cseg}, @samp{offset}, @samp{cseg_16},
1N/A@samp{dseg}, @samp{flags}, @samp{cseg_len}, @samp{cseg_16_len},
1N/A@samp{dseg_len} indicate the version number, the protected mode 32-bit
1N/Acode segment, the offset of the entry point, the protected mode 16-bit
1N/Acode segment, the protected mode 16-bit data segment, the flags, the
1N/Alength of the protected mode 32-bit code segment, the length of the
1N/Aprotected mode 16-bit code segment, and the length of the protected mode
1N/A16-bit data segment, respectively. Only the field @samp{offset} is 4
1N/Abytes, and the others are 2 bytes. See
1N/AManagement (APM) BIOS Interface Specification}, for more information.
1N/AIf bit 11 in the @samp{flags} is set, the graphics table is available.
1N/AThis must only be done if the kernel has indicated in the
1N/A@samp{Multiboot Header} that it accepts a graphics mode.
1N/AThe fields @samp{vbe_control_info} and @samp{vbe_mode_info} contain
1N/Athe physical addresses of @sc{vbe} control information returned by the
1N/A@sc{vbe} Function 00h and @sc{vbe} mode information returned by the
1N/A@sc{vbe} Function 01h, respectively.
1N/AThe field @samp{vbe_mode} indicates current video mode in the format
1N/Aspecified in @sc{vbe} 3.0.
1N/AThe rest fields @samp{vbe_interface_seg}, @samp{vbe_interface_off}, and
1N/A@samp{vbe_interface_len} contain the table of a protected mode interface
1N/Adefined in @sc{vbe} 2.0+. If this information is not available, those
1N/Afields contain zero. Note that @sc{vbe} 3.0 defines another protected
1N/Amode interface which is incompatible with the old one. If you want to
1N/Ause the new protected mode interface, you will have to find the table
1N/AThe fields for the graphics table are designed for @sc{vbe}, but
1N/AMultiboot boot loaders may simulate @sc{vbe} on non-@sc{vbe} modes, as
1N/Aif they were @sc{vbe} modes.
1N/A@strong{Caution:} The following items are not part of the specification
1N/Adocument, but are included for prospective operating system and boot
1N/A* BIOS device mapping techniques::
1N/A* Example boot loader code::
1N/AIn reference to bit 0 of the @samp{flags} parameter in the Multiboot
1N/Ainformation structure, if the bootloader in question uses older
1N/A@sc{bios} interfaces, or the newest ones are not available (see
1N/Adescription about bit 6), then a maximum of either 15 or 63 megabytes of
1N/Amemory may be reported. It is @emph{highly} recommended that boot
1N/Aloaders perform a thorough memory probe.
1N/AIn reference to bit 1 of the @samp{flags} parameter in the Multiboot
1N/Ainformation structure, it is recognized that determination of which
1N/A@sc{bios} drive maps to which device driver in an operating system is
1N/Anon-trivial, at best. Many kludges have been made to various operating
1N/Asystems instead of solving this problem, most of them breaking under
1N/Amany conditions. To encourage the use of general-purpose solutions to
1N/Athis problem, there are 2 @sc{bios} device mapping techniques
1N/A(@pxref{BIOS device mapping techniques}).
1N/AIn reference to bit 6 of the @samp{flags} parameter in the Multiboot
1N/Ainformation structure, it is important to note that the data structure
1N/Aused there (starting with @samp{BaseAddrLow}) is the data returned by
1N/Athe INT 15h, AX=E820h --- Query System Address Map call. See @xref{Query
1N/ASystem Address Map, , Query System Address Map,
grub.info, The GRUB
1N/AManual}, for more information. The interface here is meant to allow a
1N/Aboot loader to work unmodified with any reasonable extensions of the
1N/A@sc{bios} interface, passing along any extra data to be interpreted by
1N/Athe operating system as desired.
1N/A@node BIOS device mapping techniques
1N/A@section BIOS device mapping techniques
1N/ABoth of these techniques should be usable from any PC operating system,
1N/Aand neither require any special support in the drivers themselves. This
1N/Asection will be flushed out into detailed explanations, particularly for
1N/Athe I/O restriction technique.
1N/AThe general rule is that the data comparison technique is the quick and
1N/Adirty solution. It works most of the time, but doesn't cover all the
1N/Abases, and is relatively simple.
1N/AThe I/O restriction technique is much more complex, but it has potential
1N/Ato solve the problem under all conditions, plus allow access of the
1N/Aremaining @sc{bios} devices when not all of them have operating system
1N/A* Data comparison technique::
1N/A* I/O restriction technique::
1N/A@node Data comparison technique
1N/A@subsection Data comparison technique
1N/ABefore activating @emph{any} of the device drivers, gather enough data
1N/Afrom similar sectors on each of the disks such that each one can be
1N/AAfter activating the device drivers, compare data from the drives using
1N/Athe operating system drivers. This should hopefully be sufficient to
1N/Aprovide such a mapping.
1N/AThe data on some @sc{bios} devices might be identical (so the part
1N/Areading the drives from the @sc{bios} should have some mechanism to give
1N/AThere might be extra drives not accessible from the @sc{bios} which are
1N/Aidentical to some drive used by the @sc{bios} (so it should be capable
1N/Aof giving up there as well).
1N/A@node I/O restriction technique
1N/A@subsection I/O restriction technique
1N/AThis first step may be unnecessary, but first create copy-on-write
1N/Amappings for the device drivers writing into @sc{pc} @sc{ram}. Keep the
1N/Aoriginal copies for the @dfn{clean @sc{bios} virtual machine} to be
1N/AFor each device driver brought online, determine which @sc{bios} devices
1N/Abecome inaccessible by:
1N/ACreate a @dfn{clean @sc{bios} virtual machine}.
1N/ASet the I/O permission map for the I/O area claimed by the device driver
1N/Ato no permissions (neither read nor write).
1N/ARecord which devices succeed, and those which try to access the
1N/A@dfn{restricted} I/O areas (hopefully, this will be an @dfn{xor}
1N/AFor each device driver, given how many of the @sc{bios} devices were
1N/Asubsumed by it (there should be no gaps in this list), it should be easy
1N/Ato determine which devices on the controller these are.
1N/AIn general, you have at most 2 disks from each controller given
1N/A@sc{bios} numbers, but they pretty much always count from the lowest
1N/Alogically numbered devices on the controller.
1N/A@node Example OS code
1N/A@section Example OS code
1N/AIn this distribution, the example Multiboot kernel @file{kernel} is
1N/Aincluded. The kernel just prints out the Multiboot information structure
1N/Aon the screen, so you can make use of the kernel to test a
1N/AMultiboot-compliant boot loader and for reference to how to implement a
1N/AMultiboot kernel. The source files can be found under the directory
1N/A@file{docs} in the GRUB distribution.
1N/AThe kernel @file{kernel} consists of only three files: @file{
boot.S},
1N/AThe GNU assembler}), and contains the Multiboot information structure to
1N/Acomply with the specification. When a Multiboot-compliant boot loader
1N/Aloads and execute it, it initialize the stack pointer and @code{EFLAGS},
1N/Aand then call the function @code{cmain} defined in @file{
kernel.c}. If
1N/A@code{cmain} returns to the callee, then it shows a message to inform
1N/Athe user of the halt state and stops forever until you push the reset
1N/Akey. The file @file{
kernel.c} contains the function @code{cmain},
1N/Awhich checks if the magic number passed by the boot loader is valid and
1N/Aso on, and some functions to print messages on the screen. The file
1N/A@file{
multiboot.h} defines some macros, such as the magic number for the
1N/AMultiboot header, the Multiboot header structure and the Multiboot
1N/Ainformation structure.
1N/A* Other Multiboot kernels::
1N/A@node Other Multiboot kernels
1N/A@subsection Other Multiboot kernels
1N/AOther useful information should be available in Multiboot kernels, such
1N/Ait is worth mentioning the OSKit
1N/Alibrary supporting the specification.
1N/A@node Example boot loader code
1N/A@section Example boot loader code
1N/AThe GNU GRUB (@pxref{Top, , GRUB,
grub.info, The GRUB manual}) project
1N/Ais a full Multiboot-compliant boot loader, supporting all required and
1N/Aoptional features present in this specification. A public release has
1N/Anot been made, but the test release is available from:
1N/A@chapter The change log of this specification
1N/A@dfn{Multiboot Standard} is renamed to @dfn{Multiboot Specification}.
1N/AGraphics fields are added to Multiboot header.
1N/ABIOS drive information, BIOS configuration table, the name of a boot
1N/Aloader, APM information, and graphics information are added to Multiboot
1N/ARewritten in Texinfo format.
1N/ARewritten, using more strict words.
1N/AThe maintainer changes to the GNU GRUB maintainer team
1N/A@email{bug-grub@@
gnu.org}, from Bryan Ford and Erich Stefan Boleyn.
1N/AA few wording changes.
1N/AClasification of machine state passed to an operating system.
1N/AMajor changes plus HTMLification.