diff --git a/ChangeLog b/ChangeLog index 9da16af89..0e557079e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +1999-09-22 OKUJI Yoshinori + + * multiboot.texi (BIOS device mapping techniques): New section. + Stolen from bios_mapping.txt in grub-0.5. + (Data comparison technique): New subsection. + (I/O restriction technique): Likewise. + (Example OS code): Rewrited from scratch. + +1999-09-21 OKUJI Yoshinori + + * multiboot.texi: Rename Multiboot Standard to Multiboot + Specification and upgrade the version to 0.7. Many cleanups + are done. + 1999-10-15 OKUJI Yoshinori * stage2/builtins.c (setup_func): Save CURRENT_DRIVE and diff --git a/docs/multiboot.texi b/docs/multiboot.texi index 0a01ad2bc..6792c28f8 100644 --- a/docs/multiboot.texi +++ b/docs/multiboot.texi @@ -7,16 +7,14 @@ @syncodeindex pg cp @syncodeindex tp cp -@c -@c This file will be included from grub.texi -@c - @dircategory Kernel @direntry -* Multiboot Standard: (multiboot). Multiboot Standard +* Multiboot Specification: (multiboot). Multiboot Specification. @end direntry @ifinfo +Copyright @copyright{} 1995, 96 Bryan Ford +Copyright @copyright{} 1995, 96 Erich Stefan Boleyn Copyright @copyright{} 1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of @@ -40,15 +38,19 @@ Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. @end ifinfo -@settitle Multiboot Standard +@settitle Multiboot Specification @titlepage @finalout -@title The Multiboot Standard +@title The Multiboot Specification +@author Bryan Ford +@author Erich Stefan Boleyn @author Kunihiro Ishiguro @author OKUJI Yoshinori @page @vskip 0pt plus 1filll +Copyright @copyright{} 1995, 96 Bryan Ford +Copyright @copyright{} 1995, 96 Erich Stefan Boleyn Copyright @copyright{} 1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of @@ -64,22 +66,21 @@ Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. @end titlepage -@ifinfo +@ifnottex -@node Top, Motivation, (dir), (dir) -@comment node-name, next, previous, up -@top Multiboot Standard +@node Top +@top Multiboot Specification + +This file documents Multiboot Specification, the proposal for the boot +sequence standard. This edition documents version 0.7. +@end ifnottex -This file documents Multiboot Standard, the proposal for the boot -sequence standard. This edition documents version 0.6. @menu * Motivation:: * Terminology:: -* Scope and Requirements:: +* Scope and requirements:: * Details:: -* Authors:: -* Revision History:: * Examples:: * Index:: @@ -92,119 +93,113 @@ Scope and Requirements * Operating systems:: * Boot sources:: * Boot-time configuration:: -* Convenience to the OS:: +* Convenience to the operating system:: * Boot modules:: Details -* OS Image Format:: -* Machine State:: -* Boot Information Format:: +* OS image format:: +* Machine state:: +* Boot information format:: Examples -* Notes on PCs:: -* Example OS Code:: -* Example Bootloader Code:: +* Notes on PC:: +* BIOS device mapping techniques:: +* Example OS code:: +* Example boot loader code:: @end detailmenu @end menu -@end ifinfo - -@node Motivation, Terminology, Top, Top -@comment node-name, next, previous, up +@node Motivation @chapter Motivation -Every OS ever created tends to have its own boot loader. Installing a -new OS 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 OS doesn't -do exactly what you want, or doesn't work on your machine, you're -screwed. +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 OS communities to put their heads together and solve this problem -for the popular free operating systems. That's what this standard 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 standard does @emph{not} specify how -boot loaders should work - only how they must interface with the OS -being loaded. +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 Terminology, Scope and Requirements, Motivation, Top -@comment node-name, next, previous, up +@node Terminology @chapter Terminology Throughout this document, the term @dfn{boot loader} means 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 +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 -standard. Only the @emph{final} stage of the boot loader - the stage -that eventually transfers control to the OS - needs to follow the rules -specified in this document in order to be @dfn{MultiBoot compliant}; -earlier boot loader stages can be designed in whatever way is most -convenient. +specification. Only the @emph{final} stage of the boot loader --- the +stage that eventually transfers control to the operating system --- +needs to follow the rules specified in this document in order to be +@dfn{MultiBoot compliant}; earlier boot loader stages can be designed in +whatever way is most convenient. The term @dfn{OS image} is used to refer to the initial binary image -that the boot loader loads into memory and transfers control to to start -the OS. The OS image is typically an executable containing the OS -kernel. +that the boot loader loads into memory and transfers control to start +the operating system. The OS image is typically an executable containing +the operating system kernel. The term @dfn{boot module} refers to other auxiliary files that the boot loader loads into memory along with the OS image, but does not interpret -in any way other than passing their locations to the OS when it is -invoked. +in any way other than passing their locations to the operating system +when it is invoked. -@node Scope and Requirements, Details, Terminology, Top -@comment node-name, next, previous, up -@chapter Scope and Requirements +@node Scope and requirements +@chapter Scope and requirements @menu * Architecture:: * Operating systems:: * Boot sources:: * Boot-time configuration:: -* Convenience to the OS:: +* Convenience to the operating system:: * Boot modules:: @end menu -@node Architecture, Operating systems, Scope and Requirements, Scope and Requirements -@comment node-name, next, previous, up +@node Architecture @section Architecture -This standard is primarily targetted at PC's, since they are the most -common and have the largest variety of OS's and boot loaders. However, -to the extent that certain other architectures may need a boot standard -and do not have one already, a variation of this standard, stripped of -the x86-specific details, could be adopted for them as well. +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, Boot sources, Architecture, Scope and Requirements -@comment node-name, next, previous, up +@node Operating systems @section Operating systems -This standard is targetted toward free 32-bit operating systems that can -be fairly easily modified to support the standard without going through -lots of bureaucratic rigmarole. The particular free OS's that this -standard is being primarily designed for are Linux, FreeBSD, NetBSD, -Mach, and VSTa. It is hoped that other emerging free OS's 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 standard as well, but that's probably a -pipe dream. +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, Boot-time configuration, Operating systems, Scope and Requirements -@comment node-name, next, previous, up +@node Boot sources @section Boot sources It should be possible to write compliant boot loaders that load the OS @@ -214,135 +209,137 @@ 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{block lists} (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. +using precalculated @dfn{block lists} (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, Convenience to the OS, Boot sources, Scope and Requirements -@comment node-name, next, previous, up +@node Boot-time configuration @section Boot-time configuration It is often necessary for one reason or another for the user to be able -to provide some configuration information to the OS dynamically at boot -time. While this standard 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 OS. +to provide some configuration information to the 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 the OS, Boot modules, Boot-time configuration, Scope and Requirements -@comment node-name, next, previous, up -@section Convenience to the OS +@node Convenience to the operating system +@section Convenience to the operating system -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 -OS normally uses. It should be possible to @code{nm} or disassemble OS -images just like normal executables. Specialized tools should not be -needed to create OS images in a @emph{special} file format. If this -means shifting some work from the OS to the 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 OS 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 OS data above the 1MB -boundary, and forcing the OS to do this makes creation of OS images much -more difficult. +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 needed to create OS images in a @emph{special} file +format. If this means shifting some work from the operating system to +the 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 PC-based OS's - generally a different format -for each OS. Most of the relevant free OS's use some variant of a.out -format, but some are moving to 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 OS-specific again. +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 standard adopts a compromise solution to this problem. MultiBoot -compliant boot images always either (a) are in ELF format, or (b) -contain a @dfn{magic MultiBoot header}, described below, 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. +This specification adopts a compromise solution to this +problem. Multiboot compliant boot 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, , Convenience to the OS, Scope and Requirements -@comment node-name, next, previous, up +@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 +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 OS when it receives control, it is often more flexible, more -space-efficient, and more convenient to the OS and user if the boot -loader can load these additional modules independently in the first -place. +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 standard should provide a standard method for a boot loader -to indicate to the OS 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 OS's will be -unable to boot without them. +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 Details, Authors, Scope and Requirements, Top -@comment node-name, next, previous, up +@node Details @chapter Details -There are three main aspects of the boot-loader/OS image interface this -standard must specify: +There are three main aspects of the boot loader/OS image interface: @enumerate -@item The format of the OS image as seen by the boot loader. -@item The state of the machine when the boot loader starts the OS. -@item The format of the information passed by the boot loader to the OS. +@item +The format of the OS image as seen by the boot loader. + +@item +The state of the machine when the boot loader starts the operating +system. + +@item +The format of the information passed by the boot loader to the operating +system. @end enumerate @menu -* OS Image Format:: -* Machine State:: -* Boot Information Format:: +* OS image format:: +* Machine state:: +* Boot information format:: @end menu -@node OS Image Format, Machine State, Details, Details -@comment node-name, next, previous, up -@section OS Image Format +@node OS image format +@section OS image format An OS image is generally just an ordinary 32-bit executable file in the -standard format for that particular OS, except that it may be linked at -a non-default load address to avoid loading on top of the PC's I/O -region or other reserved areas, and of course it can't use shared -libraries or other fancy features. Initially, only images in a.out -format are supported; ELF support will probably later be specified in -the standard. +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 can't use +shared libraries or other fancy features. Unfortunately, the exact meaning of the text, data, bss, and entry fields of a.out headers tends to vary widely between different executable flavors, and it is sometimes very difficult to distinguish -one flavor from another (e.g. Linux ZMAGIC executables and Mach ZMAGIC -executables). Furthermore, there is no simple, reliable way of -determining at what address in memory the text segment is supposed to -start. Therefore, this standard requires that an additional header, -known as a @dfn{multiboot_header}, appear somewhere near the beginning of -the executable file. In general it should come @emph{as early as possible}, -and is typically embedded in the beginning of the text segment after the -@emph{real} executable header. It @emph{must} be contained completely -within the -first 8192 bytes of the executable file, and must be longword (32-bit) -aligned. These rules allow the boot loader to find and synchronize with -the text segment in the a.out file without knowing beforehand the -details of the a.out variant. The layout of the header is as follows: +one flavor from another (e.g. Linux @sc{zmagic} executables and Mach +@sc{zmagic} executables). Furthermore, there is no simple, reliable way +of determining at what address in memory the text segment is supposed to +start. Therefore, this specification requires that an additional header, +known as a @dfn{Multiboot header}, appear somewhere near the beginning +of the executable file. In general it should come @emph{as early as +possible}, and is typically embedded in the beginning of the text +segment after the @emph{real} executable header. It @emph{must} be +contained completely within the first 8192 bytes of the executable file, +and must be longword (32-bit) aligned. These rules allow the boot loader +to find and synchronize with the text segment in the a.out file without +knowing beforehand the details of the a.out variant. The layout of the +header is as follows: @example @group @@ -351,159 +348,177 @@ details of the a.out variant. The layout of the header is as follows: 4 | flags | (required) 8 | checksum | (required) +-------------------+ -8 | header_addr | (present if flags[16] is set) -12 | load_addr | (present if flags[16] is set) -16 | load_end_addr | (present if flags[16] is set) -20 | bss_end_addr | (present if flags[16] is set) -24 | entry_addr | (present if flags[16] is set) +12 | header_addr | (present if flags[16] is set) +16 | load_addr | (present if flags[16] is set) +20 | load_end_addr | (present if flags[16] is set) +24 | bss_end_addr | (present if flags[16] is set) +28 | entry_addr | (present if flags[16] is set) +-------------------+ @end group @end example -All fields are in little-endian byte order, of course. The first field +All fields are in little-endian byte order, of course. The first field is the magic number identifying the header, which must be the hex value 0x1BADB002. -The flags field specifies features that the OS image requests or -requires of the boot loader. Bits 0-15 indicate requirements; if the +The @samp{flags} field specifies features that the OS image requests or +requires of the 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 +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 can simply ignore them and proceed as usual. -Naturally, all as-yet-undefined bits in the flags word must be set to -zero in OS images. This way, the flags fields serves for version -control as well as simple feature selection. +doesn't understand them, it can 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 flags word is set, then all boot modules loaded along -with the OS must be aligned on page (4KB) boundaries. Some OS's 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 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 flags word is set, then information on available memory -via at least the @samp{mem_*} fields of the multiboot_info structure defined -below must be included. If the bootloader is capable of passing a -memory map (the @samp{mmap_*} fields) and one exists, then it must be -included as well. +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 +bootloader is capable of passing a memory map (the @samp{mmap_*} fields) +and one exists, then it must be included as well. -If bit 16 in the flags word is set, then the fields at offsets 8-24 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 ELF format, but it should 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 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. +If bit 16 in the @samp{flags} word is set, then the fields at offsets +8-24 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. 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 +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 +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. +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. +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. @item bss_end_addr -Contains the physical address of the end of the bss segment. The boot +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 OS -in that area. +occupies to avoid placing boot modules and other data relevant to the +operating system in that area. -@item entry +@item entry_addr The physical address to which the boot loader should jump in order to -start running the OS. +start running the operating system. @end table The checksum is a 32-bit unsigned value which, when added to the other required fields, must have a 32-bit unsigned sum of zero. -@node Machine State, Boot Information Format, OS Image Format, Details -@comment node-name, next, previous, up -@section Machine State +@node Machine state +@section Machine state -When the boot loader invokes the 32-bit operating system, -the machine must have the following state: +When the boot loader invokes the 32-bit operating system, the machine +must have the following state: @itemize @bullet -@item @code{CS} must be a 32-bit read/execute code segment with an offset of 0 -and a limit of 0xffffffff. +@item +@code{CS} must be a 32-bit read/execute code segment with an offset of 0 +and a limit of 0xFFFFFFFF. -@item @code{DS}, @code{ES}, @code{FS}, @code{GS}, and @code{SS} must be a 32-bit read/write data segment with -an offset of 0 and a limit of 0xffffffff. +@item +@code{DS}, @code{ES}, @code{FS}, @code{GS}, and @code{SS} must be a +32-bit read/write data segment with an offset of 0 and a limit of +0xFFFFFFFF. -@item The address 20 line must be usable for standard linear 32-bit -addressing of memory (in standard PC hardware, it is wired to -0 at bootup, forcing addresses in the 1-2 MB range to be mapped to the -0-1 MB range, 3-4 is mapped to 2-3, etc.). +@item +The address 20 line must be usable for standard linear 32-bit addressing +of memory (in standard @sc{pc} hardware, it is wired to 0 at bootup, +forcing addresses in the 1-2 MB range to be mapped to the 0-1 MB range, +3-4 is mapped to 2-3, etc.). -@item Paging must be turned off. +@item +Paging must be turned off. -@item The processor interrupt flag must be turned off. +@item +The processor interrupt flag must be turned off. -@item @code{EAX} must contain the magic value 0x2BADB002; the presence of this value -indicates to the OS that it was loaded by a MultiBoot-compliant boot -loader (e.g. as opposed to another type of boot loader that the OS can -also be loaded from). +@item +@code{EAX} must contain the magic value 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 @code{EBX} must contain the 32-bit physical address of the multiboot_info -structure provided by the boot loader (see below). +@item +@code{EBX} must contain the 32-bit physical address of the Multiboot +information structure provided by the boot loader (@pxref{Boot +information format}). @end itemize -All other processor registers and flag bits are undefined. This includes, -in particular: +All other processor registers and flag bits are undefined. This +includes, in particular: @itemize @bullet +@item +@code{ESP}: the 32-bit operating system must create its own stack as +soon as it needs one. -@item @code{ESP}: the 32-bit OS must create its own stack as soon as it needs one. +@item +@code{GDTR}: Even though the segment registers are set up as described +above, the @code{GDTR} may be invalid, so the operating system must not +load any segment registers (even just reloading the same values!) until +it sets up its own @code{GDT}. -@item @code{GDTR}: Even though the segment registers are set up as described above, the @code{GDTR} may be invalid, so the OS must not load any segment registers (even just reloading the same values!) until it sets up its own @code{GDT}. - -@item @code{IDTR}: The OS must leave interrupts disabled until it sets up its own @code{IDT}. +@item +@code{IDTR}: The operating system must leave interrupts disabled until +it sets up its own @code{IDT}. @end itemize -However, other machine state should be left by the boot loader in "normal -working order", i.e. as initialized by the BIOS (or DOS, if that's what -the boot loader runs from). In other words, the OS should be able to make -BIOS calls and such after being loaded, as long as it does not overwrite -the BIOS data structures before doing so. Also, the boot loader must leave -the PIC programmed with the normal BIOS/DOS values, even if it changed them -during the switch to 32-bit mode. +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, , Machine State, Details -@comment node-name, next, previous, up -@section Boot Information Format +@node Boot information format +@section Boot information format -Upon entry to the OS, the @code{EBX} register contains the physical -address of a 'multiboot_info' data structure, through which the boot -loader communicates vital information to the OS. The OS can use or -ignore any parts of the structure as it chooses; all information passed -by the boot loader is advisory only. +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_info 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 OS's -responsibility to avoid overwriting this memory until it is done using it. +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_info structure (as defined so far) follows: +The format of the Multiboot information structure (as defined so far) +follows: @example @group @@ -529,28 +544,30 @@ The format of the multiboot_info structure (as defined so far) follows: @end group @end example -The first longword indicates the presence and validity of other fields in -the multiboot_info structure. All as-yet-undefined bits must be set to -zero by the boot loader. Any set bits that the OS does not understand -should be ignored. Thus, the flags field also functions as a version -indicator, allowing the multiboot_info structure to be expanded in the -future without breaking anything. +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 multiboot_info.flags word is set, then the @samp{mem_*} fields +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. +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 multiboot_info.flags word is set, then the @samp{boot_device} -field is valid, and indicates which BIOS disk device the boot loader loaded -the OS from. If the OS was not loaded from a BIOS disk, then this field -must not be present (bit 3 must be clear). The OS may use this field as a -hint for determining its own @dfn{root} device, but is not required to. The -boot_device field is layed out in four one-byte subfields as follows: +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 @@ -560,42 +577,43 @@ boot_device field is layed out in four one-byte subfields as follows: @end group @end example -The first byte contains the BIOS drive number as understood by the BIOS -INT 0x13 low-level disk interface: e.g. 0x00 for the first floppy disk -or 0x80 for the first hard disk. +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} +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. +@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. +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 flags longword is set, the @samp{cmdline} field is valid, and -contains the physical address of the the command line to be passed to the -kernel. The command line is a normal C-style null-terminated string. +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 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: +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 @@ -610,21 +628,21 @@ bit 1 of @samp{flags} is set. Each module structure is formatted as follows: @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 null-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 OS treats boot modules as executable programs), -or a pathname (e.g. if the OS treats boot modules as files in a file -system), but its exact use is specific to the OS. The @samp{reserved} field -must be set to 0 by the boot loader and ignored by the OS. +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 multiboot_info.flags word is set, then the following -fields in the multiboot_info structure starting at byte 28 are valid: +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 @@ -639,18 +657,18 @@ fields in the multiboot_info structure starting at byte 28 are valid: 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 -null-terminated 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 flags -word is set. +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 multiboot_info.flags word is set, then the following -fields in the multiboot_info structure starting at byte 28 are valid: +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 @@ -665,200 +683,227 @@ fields in the multiboot_info structure starting at byte 28 are valid: 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 (ELF) specification in the program -header. All sections are loaded, and the physical address fields -of the elf section header then refer to where the sections are in memory -(refer to the i386 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 flags word is set. +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 multiboot_info.flags word is set, then the @samp{mmap_*} fields +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 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): +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 | BaseAddrLow | -4 | BaseAddrHigh | -8 | LengthLow | -12 | LengthHigh | -16 | Type | +0 | base_addr_low | +4 | base_addr_high | +8 | length_low | +12 | length_high | +16 | type | +-------------------+ @end group @end example -where @dfn{size} is the size of the associated structure in bytes, which -can be greater than the minimum of 20 bytes. @dfn{BaseAddrLow} is the -lower 32 bits of the starting address, and @dfn{BaseAddrHigh} is the -upper 32 bits, for a total of a 64-bit starting address. -@dfn{LengthLow} is the lower 32 bits of the size of the memory region in -bytes, and @dfn{LengthHigh} is the upper 32 bits, for a total of a -64-bit length. @dfn{Type} is the variety of address range represented, -where a value of 1 indicates available RAM, and all other values -currently indicated a reserved area. +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 RAM that should +The map provided is guaranteed to list all standard @sc{ram} that should be available for normal use. -@node Authors, Revision History, Details, Top -@comment node-name, next, previous, up -@chapter Authors - -@example -Bryan Ford -Computer Systems Laboratory -University of Utah -Salt Lake City, UT 84112 -(801) 581-4280 -baford@@cs.utah.edu -@end example - -@example -Erich Stefan Boleyn -924 S.W. 16th Ave, #202 -Portland, OR, USA 97205 -(503) 226-0741 -erich@@uruk.org -@end example - -We would also like to thank the many other people have provided comments, -ideas, information, and other forms of support for our work. - - -@node Revision History, Examples, Authors, Top -@comment node-name, next, previous, up -@chapter Revision History - -@example -Version 0.6 3/29/96 (a few wording changes, header checksum, and - clarification of machine state passed to the OS) -Version 0.5 2/23/96 (name change) -Version 0.4 2/1/96 (major changes plus HTMLification) -Version 0.3 12/23/95 -Version 0.2 10/22/95 -Version 0.1 6/26/95 -@end example - - -@node Examples, Index, Revision History, Top -@comment node-name, next, previous, up +@node Examples @chapter Examples -NOTE: The following items are not part of the standards document, but -are included for prospective OS and bootloader writers. +@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 PCs:: -* Example OS Code:: -* Example Bootloader Code:: +* Notes on PC:: +* BIOS device mapping techniques:: +* Example OS code:: +* Example boot loader code:: @end menu -@node Notes on PCs, Example OS Code, Examples, Examples -@comment node-name, next, previous, up -@section Notes on PCs +@node Notes on PC +@section Notes on PC -In reference to bit 0 of the multiboot_info.flags parameter, -if the bootloader -in question uses older 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 bootloaders perform a thorough memory probe. +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 multiboot_info.flags parameter, it is -recognized that determination of which BIOS drive maps to which -OS-level device-driver is non-trivial, at best. Many kludges have -been made to various OSes instead of solving this problem, most of -them breaking under many conditions. To encourage the use of -general-purpose solutions to this problem, here are 2 -@uref{file:bios_mapping}BIOS Device Mapping Techniques. +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 multiboot_info.flags parameter, it is -important to note that the data structure used there (starting with -@samp{BaseAddrLow}) is the data returned by the @uref{file:mem64mb} INT 15h, -AX=E820h - Query System Address Map call. More information on reserved -memory regions is defined on that web page. The interface here is meant -to allow a bootloader to work unmodified with any reasonable extensions -of the BIOS interface, passing along any extra data to be interpreted by -the OS as desired. +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 Example OS Code, Example Bootloader Code, Notes on PCs, Examples -@comment node-name, next, previous, up -@section Example OS Code +@node BIOS device mapping techniques +@section BIOS device mapping techniques -@strong{Caution:} These examples are relevant to the Proposal version 0.5, -which is basically identical except for the multiboot OS header, which was -missing the checksum. A patch to bring Mach4 UK22 up to version 0.6 is -available in the GRUB FTP area mentioned in the -@ref{Example Bootloader Code} section below. +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 Mach 4 distribution, available by anonymous FTP from -@url{ftp://flux.cs.utah.edu:/flux}, contains a C header file that defines the -MultiBoot data structures described above; anyone is welcome to rip it -out and use it for other boot loaders and OS's: +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. -@example -mach4-i386/include/mach/machine/multiboot.h -@end example +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. -This distribution also contains code implementing a @dfn{Linux boot -adaptor}, which collects a MultiBoot-compliant OS image and an optional -set of boot modules, compresses them, and packages them into a single -traditional Linux boot image that can be loaded from LILO or other Linux -boot loaders. There is also a corresponding @dfn{BSD boot adaptor} which -can be used to wrap a MultiBoot kernel and set of modules and produce an -image that can be loaded from the FreeBSD and NetBSD boot loaders. All -of this code can be used as-is or as a basis for other boot loaders. -These are the directories of primary relevance: - -@example -mach4-i386/boot -mach4-i386/boot/bsd -mach4-i386/boot/linux -@end example - -The Mach kernel itself in this distribution contains code that demonstrates -how to create a compliant OS. The following files are of primary -relevance: - -@example -mach4-i386/kernel/i386at/boothdr.S -mach4-i386/kernel/i386at/model_dep.c -@end example - -Finally, I have created patches against the Linux 1.2.2 and FreeBSD 2.0 -kernels, in order to make them compliant with this proposed standard. -These patches are available in -@url{ftp://kahlua.cs.utah.edu:/private/boot}. +@menu +* Data comparison technique:: +* I/O restriction technique:: +@end menu -@node Example Bootloader Code, , Example OS Code, Examples -@comment node-name, next, previous, up -@section Example Bootloader Code +@node Data comparison technique +@subsection Data comparison technique -The GRUB bootloader project @url{http://www.uruk.org/grub/} will be -fully Multiboot-compliant, supporting all required and optional features -present in this standard. +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. -A final release has not been made, but both the GRUB beta release (which -is quite stable) and a patch for Multiboot version 0.6 for Mach4 UK22 -are available in the GRUB public release area -@url{ftp://ftp.uruk.org/public/grub/} . +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 Index, , Examples, Top -@comment node-name, next, previous, up +@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 image and the source files can be found in the +data directory (usually, @file{/usr/share/multiboot} or +@file{/usr/local/share/multiboot}). + +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. See the source files for more information. + +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 +@url{http://www.gnu.org/software/grub/grub.en.html} 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 in +@url{ftp://alpha.gnu.org/gnu/hurd/src/}. + + +@node Index @unnumbered Index @printindex cp