1 \input texinfo @c -*-texinfo-*- 2 @c -*-texinfo-*- 3 @c %**start of header 4 @setfilename multiboot.info 5 @settitle Multiboot Specification 6 @c %**end of header 7 8 @c Unify all our little indices for now. 9 @syncodeindex fn cp 10 @syncodeindex vr cp 11 @syncodeindex ky cp 12 @syncodeindex pg cp 13 @syncodeindex tp cp 14 15 @footnotestyle separate 16 @paragraphindent 3 17 @finalout 18 19 20 @dircategory Kernel 21 @direntry 22 * Multiboot Specification: (multiboot). Multiboot Specification. 23 @end direntry 24 25 @ifinfo 26 Copyright @copyright{} 1995, 96 Bryan Ford <baford@@cs.utah.edu> 27 Copyright @copyright{} 1995, 96 Erich Stefan Boleyn <erich@@uruk.org> 28 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc. 29 30 Permission is granted to make and distribute verbatim copies of 31 this manual provided the copyright notice and this permission notice 32 are preserved on all copies. 33 34 @ignore 35 Permission is granted to process this file through TeX and print the 36 results, provided the printed document carries a copying permission 37 notice identical to this one except for the removal of this paragraph 38 (this paragraph not being relevant to the printed manual). 39 40 @end ignore 41 42 Permission is granted to copy and distribute modified versions of this 43 manual under the conditions for verbatim copying, provided also that 44 the entire resulting derived work is distributed under the terms of a 45 permission notice identical to this one. 46 47 Permission is granted to copy and distribute translations of this manual 48 into another language, under the above conditions for modified versions. 49 @end ifinfo 50 51 @titlepage 52 @sp 10 53 @title The Multiboot Specification 54 @author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn, Kunihiro Ishiguro 55 @page 56 57 @vskip 0pt plus 1filll 58 Copyright @copyright{} 1995, 96 Bryan Ford <baford@@cs.utah.edu> 59 Copyright @copyright{} 1995, 96 Erich Stefan Boleyn <erich@@uruk.org> 60 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc. 61 62 Permission is granted to make and distribute verbatim copies of 63 this manual provided the copyright notice and this permission notice 64 are preserved on all copies. 65 66 Permission is granted to copy and distribute modified versions of this 67 manual under the conditions for verbatim copying, provided also that 68 the entire resulting derived work is distributed under the terms of a 69 permission notice identical to this one. 70 71 Permission is granted to copy and distribute translations of this manual 72 into another language, under the above conditions for modified versions. 73 @end titlepage 74 75 @finalout 76 @headings double 77 78 @ifnottex 79 @node Top 80 @top Multiboot Specification 81 82 This file documents Multiboot Specification, the proposal for the boot 83 sequence standard. This edition documents version 0.6.93. 84 @end ifnottex 85 86 @menu 87 * Overview:: 88 * Terminology:: 89 * Specification:: 90 * Examples:: 91 * History:: 92 * Index:: 93 @end menu 94 95 96 @node Overview 97 @chapter Introduction to Multiboot Specification 98 99 This chapter describes some rough information on the Multiboot 100 Specification. Note that this is not a part of the specification itself. 101 102 @menu 103 * Motivation:: 104 * Architecture:: 105 * Operating systems:: 106 * Boot sources:: 107 * Boot-time configuration:: 108 * Convenience to operating systems:: 109 * Boot modules:: 110 @end menu 111 112 113 @node Motivation 114 @section The background of Multiboot Specification 115 116 Every operating system ever created tends to have its own boot loader. 117 Installing a new operating system on a machine generally involves 118 installing a whole new set of boot mechanisms, each with completely 119 different install-time and boot-time user interfaces. Getting multiple 120 operating systems to coexist reliably on one machine through typical 121 @dfn{chaining} mechanisms can be a nightmare. There is little or no 122 choice of boot loaders for a particular operating system --- if the one 123 that comes with the operating system doesn't do exactly what you want, 124 or doesn't work on your machine, you're screwed. 125 126 While we may not be able to fix this problem in existing commercial 127 operating systems, it shouldn't be too difficult for a few people in the 128 free operating system communities to put their heads together and solve 129 this problem for the popular free operating systems. That's what this 130 specification aims for. Basically, it specifies an interface between a 131 boot loader and a operating system, such that any complying boot loader 132 should be able to load any complying operating system. This 133 specification does @emph{not} specify how boot loaders should work --- 134 only how they must interface with the operating system being loaded. 135 136 137 @node Architecture 138 @section The target architecture 139 140 This specification is primarily targeted at @sc{pc}, since they are the 141 most common and have the largest variety of operating systems and boot 142 loaders. However, to the extent that certain other architectures may 143 need a boot specification and do not have one already, a variation of 144 this specification, stripped of the x86-specific details, could be 145 adopted for them as well. 146 147 148 @node Operating systems 149 @section The target operating systems 150 151 This specification is targeted toward free 32-bit operating systems 152 that can be fairly easily modified to support the specification without 153 going through lots of bureaucratic rigmarole. The particular free 154 operating systems that this specification is being primarily designed 155 for are Linux, FreeBSD, NetBSD, Mach, and VSTa. It is hoped that other 156 emerging free operating systems will adopt it from the start, and thus 157 immediately be able to take advantage of existing boot loaders. It would 158 be nice if commercial operating system vendors eventually adopted this 159 specification as well, but that's probably a pipe dream. 160 161 162 @node Boot sources 163 @section Boot sources 164 165 It should be possible to write compliant boot loaders that load the OS 166 image from a variety of sources, including floppy disk, hard disk, and 167 across a network. 168 169 Disk-based boot loaders may use a variety of techniques to find the 170 relevant OS image and boot module data on disk, such as by 171 interpretation of specific file systems (e.g. the BSD/Mach boot loader), 172 using precalculated @dfn{block lists} (e.g. LILO), loading from a 173 special @dfn{boot partition} (e.g. OS/2), or even loading from within 174 another operating system (e.g. the VSTa boot code, which loads from 175 DOS). Similarly, network-based boot loaders could use a variety of 176 network hardware and protocols. 177 178 It is hoped that boot loaders will be created that support multiple 179 loading mechanisms, increasing their portability, robustness, and 180 user-friendliness. 181 182 183 @node Boot-time configuration 184 @section Configure an operating system at boot-time 185 186 It is often necessary for one reason or another for the user to be able 187 to provide some configuration information to an operating system 188 dynamically at boot time. While this specification should not dictate 189 how this configuration information is obtained by the boot loader, it 190 should provide a standard means for the boot loader to pass such 191 information to the operating system. 192 193 194 @node Convenience to operating systems 195 @section How to make OS development easier 196 197 OS images should be easy to generate. Ideally, an OS image should simply 198 be an ordinary 32-bit executable file in whatever file format the 199 operating system normally uses. It should be possible to @code{nm} or 200 disassemble OS images just like normal executables. Specialized tools 201 should not be required to create OS images in a @emph{special} file 202 format. If this means shifting some work from the operating system to 203 a boot loader, that is probably appropriate, because all the memory 204 consumed by the boot loader will typically be made available again after 205 the boot process is created, whereas every bit of code in the OS image 206 typically has to remain in memory forever. The operating system should 207 not have to worry about getting into 32-bit mode initially, because mode 208 switching code generally needs to be in the boot loader anyway in order 209 to load operating system data above the 1MB boundary, and forcing the 210 operating system to do this makes creation of OS images much more 211 difficult. 212 213 Unfortunately, there is a horrendous variety of executable file formats 214 even among free Unix-like @sc{pc}-based operating systems --- generally 215 a different format for each operating system. Most of the relevant free 216 operating systems use some variant of a.out format, but some are moving 217 to @sc{elf}. It is highly desirable for boot loaders not to have to be 218 able to interpret all the different types of executable file formats in 219 existence in order to load the OS image --- otherwise the boot loader 220 effectively becomes operating system specific again. 221 222 This specification adopts a compromise solution to this 223 problem. Multiboot-compliant OS images always contain a magic 224 @dfn{Multiboot header} (@pxref{OS image format}), which allows the boot 225 loader to load the image without having to understand numerous a.out 226 variants or other executable formats. This magic header does not need to 227 be at the very beginning of the executable file, so kernel images can 228 still conform to the local a.out format variant in addition to being 229 Multiboot-compliant. 230 231 232 @node Boot modules 233 @section Boot modules 234 235 Many modern operating system kernels, such as those of VSTa and Mach, do 236 not by themselves contain enough mechanism to get the system fully 237 operational: they require the presence of additional software modules at 238 boot time in order to access devices, mount file systems, etc. While 239 these additional modules could be embedded in the main OS image along 240 with the kernel itself, and the resulting image be split apart manually 241 by the operating system when it receives control, it is often more 242 flexible, more space-efficient, and more convenient to the operating 243 system and user if the boot loader can load these additional modules 244 independently in the first place. 245 246 Thus, this specification should provide a standard method for a boot 247 loader to indicate to the operating system what auxiliary boot modules 248 were loaded, and where they can be found. Boot loaders don't have to 249 support multiple boot modules, but they are strongly encouraged to, 250 because some operating systems will be unable to boot without them. 251 252 253 @node Terminology 254 @chapter The definitions of terms used through the specification 255 256 @table @dfn 257 @item must 258 We use the term @dfn{must}, when any boot loader or OS image needs to 259 follow a rule --- otherwise, the boot loader or OS image is @emph{not} 260 Multiboot-compliant. 261 262 @item should 263 We use the term @dfn{should}, when any boot loader or OS image is 264 recommended to follow a rule, but it doesn't need to follow the rule. 265 266 @item may 267 We use the term @dfn{may}, when any boot loader or OS image is allowed 268 to follow a rule. 269 270 @item boot loader 271 Whatever program or set of programs loads the image of the final 272 operating system to be run on the machine. The boot loader may itself 273 consist of several stages, but that is an implementation detail not 274 relevant to this specification. Only the @emph{final} stage of the boot 275 loader --- the stage that eventually transfers control to an operating 276 system --- must follow the rules specified in this document in order 277 to be @dfn{Multiboot-compliant}; earlier boot loader stages may be 278 designed in whatever way is most convenient. 279 280 @item OS image 281 The initial binary image that a boot loader loads into memory and 282 transfers control to start an operating system. The OS image is 283 typically an executable containing the operating system kernel. 284 285 @item boot module 286 Other auxiliary files that a boot loader loads into memory along with 287 an OS image, but does not interpret in any way other than passing their 288 locations to the operating system when it is invoked. 289 290 @item Multiboot-compliant 291 A boot loader or an OS image which follows the rules defined as 292 @dfn{must} is Multiboot-compliant. When this specification specifies a 293 rule as @dfn{should} or @dfn{may}, a Multiboot-complaint boot loader/OS 294 image doesn't need to follow the rule. 295 296 @item u8 297 The type of unsigned 8-bit data. 298 299 @item u16 300 The type of unsigned 16-bit data. Because the target architecture is 301 little-endian, u16 is coded in little-endian. 302 303 @item u32 304 The type of unsigned 32-bit data. Because the target architecture is 305 little-endian, u32 is coded in little-endian. 306 307 @item u64 308 The type of unsigned 64-bit data. Because the target architecture is 309 little-endian, u64 is coded in little-endian. 310 @end table 311 312 313 @node Specification 314 @chapter The exact definitions of Multiboot Specification 315 316 There are three main aspects of a boot loader/OS image interface: 317 318 @enumerate 319 @item 320 The format of an OS image as seen by a boot loader. 321 322 @item 323 The state of a machine when a boot loader starts an operating 324 system. 325 326 @item 327 The format of information passed by a boot loader to an operating 328 system. 329 @end enumerate 330 331 @menu 332 * OS image format:: 333 * Machine state:: 334 * Boot information format:: 335 @end menu 336 337 338 @node OS image format 339 @section OS image format 340 341 An OS image may be an ordinary 32-bit executable file in the standard 342 format for that particular operating system, except that it may be 343 linked at a non-default load address to avoid loading on top of the 344 @sc{pc}'s I/O region or other reserved areas, and of course it should 345 not use shared libraries or other fancy features. 346 347 An OS image must contain an additional header called @dfn{Multiboot 348 header}, besides the headers of the format used by the OS image. The 349 Multiboot header must be contained completely within the first 8192 350 bytes of the OS image, and must be longword (32-bit) aligned. In 351 general, it should come @emph{as early as possible}, and may be 352 embedded in the beginning of the text segment after the @emph{real} 353 executable header. 354 355 @menu 356 * Header layout:: The layout of Multiboot header 357 * Header magic fields:: The magic fields of Multiboot header 358 * Header address fields:: 359 * Header graphics fields:: 360 @end menu 361 362 363 @node Header layout 364 @subsection The layout of Multiboot header 365 366 The layout of the Multiboot header must be as follows: 367 368 @multitable @columnfractions .1 .1 .2 .5 369 @item Offset @tab Type @tab Field Name @tab Note 370 @item 0 @tab u32 @tab magic @tab required 371 @item 4 @tab u32 @tab flags @tab required 372 @item 8 @tab u32 @tab checksum @tab required 373 @item 12 @tab u32 @tab header_addr @tab if flags[16] is set 374 @item 16 @tab u32 @tab load_addr @tab if flags[16] is set 375 @item 20 @tab u32 @tab load_end_addr @tab if flags[16] is set 376 @item 24 @tab u32 @tab bss_end_addr @tab if flags[16] is set 377 @item 28 @tab u32 @tab entry_addr @tab if flags[16] is set 378 @item 32 @tab u32 @tab mode_type @tab if flags[2] is set 379 @item 36 @tab u32 @tab width @tab if flags[2] is set 380 @item 40 @tab u32 @tab height @tab if flags[2] is set 381 @item 44 @tab u32 @tab depth @tab if flags[2] is set 382 @end multitable 383 384 The fields @samp{magic}, @samp{flags} and @samp{checksum} are defined in 385 @ref{Header magic fields}, the fields @samp{header_addr}, 386 @samp{load_addr}, @samp{load_end_addr}, @samp{bss_end_addr} and 387 @samp{entry_addr} are defined in @ref{Header address fields}, and the 388 fields @samp{mode_type}, @samp{width}, @samp{height} and @samp{depth} are 389 defind in @ref{Header graphics fields}. 390 391 392 @node Header magic fields 393 @subsection The magic fields of Multiboot header 394 395 @table @samp 396 @item magic 397 The field @samp{magic} is the magic number identifying the header, 398 which must be the hexadecimal value @code{0x1BADB002}. 399 400 @item flags 401 The field @samp{flags} specifies features that the OS image requests or 402 requires of an boot loader. Bits 0-15 indicate requirements; if the 403 boot loader sees any of these bits set but doesn't understand the flag 404 or can't fulfill the requirements it indicates for some reason, it must 405 notify the user and fail to load the OS image. Bits 16-31 indicate 406 optional features; if any bits in this range are set but the boot loader 407 doesn't understand them, it may simply ignore them and proceed as 408 usual. Naturally, all as-yet-undefined bits in the @samp{flags} word 409 must be set to zero in OS images. This way, the @samp{flags} fields 410 serves for version control as well as simple feature selection. 411 412 If bit 0 in the @samp{flags} word is set, then all boot modules loaded 413 along with the operating system must be aligned on page (4KB) 414 boundaries. Some operating systems expect to be able to map the pages 415 containing boot modules directly into a paged address space during 416 startup, and thus need the boot modules to be page-aligned. 417 418 If bit 1 in the @samp{flags} word is set, then information on available 419 memory via at least the @samp{mem_*} fields of the Multiboot information 420 structure (@pxref{Boot information format}) must be included. If the 421 boot loader is capable of passing a memory map (the @samp{mmap_*} fields) 422 and one exists, then it may be included as well. 423 424 If bit 2 in the @samp{flags} word is set, information about the video 425 mode table (@pxref{Boot information format}) must be available to the 426 kernel. 427 428 If bit 16 in the @samp{flags} word is set, then the fields at offsets 429 8-24 in the Multiboot header are valid, and the boot loader should use 430 them instead of the fields in the actual executable header to calculate 431 where to load the OS image. This information does not need to be 432 provided if the kernel image is in @sc{elf} format, but it @emph{must} 433 be provided if the images is in a.out format or in some other 434 format. Compliant boot loaders must be able to load images that either 435 are in @sc{elf} format or contain the load address information embedded 436 in the Multiboot header; they may also directly support other executable 437 formats, such as particular a.out variants, but are not required to. 438 439 @item checksum 440 The field @samp{checksum} is a 32-bit unsigned value which, when added 441 to the other magic fields (i.e. @samp{magic} and @samp{flags}), must 442 have a 32-bit unsigned sum of zero. 443 @end table 444 445 446 @node Header address fields 447 @subsection The address fields of Multiboot header 448 449 All of the address fields enabled by flag bit 16 are physical addresses. 450 The meaning of each is as follows: 451 452 @table @code 453 @item header_addr 454 Contains the address corresponding to the beginning of the Multiboot 455 header --- the physical memory location at which the magic value is 456 supposed to be loaded. This field serves to @dfn{synchronize} the 457 mapping between OS image offsets and physical memory addresses. 458 459 @item load_addr 460 Contains the physical address of the beginning of the text segment. The 461 offset in the OS image file at which to start loading is defined by the 462 offset at which the header was found, minus (header_addr - 463 load_addr). load_addr must be less than or equal to header_addr. 464 465 @item load_end_addr 466 Contains the physical address of the end of the data 467 segment. (load_end_addr - load_addr) specifies how much data to load. 468 This implies that the text and data segments must be consecutive in the 469 OS image; this is true for existing a.out executable formats. 470 If this field is zero, the boot loader assumes that the text and data 471 segments occupy the whole OS image file. 472 473 @item bss_end_addr 474 Contains the physical address of the end of the bss segment. The boot 475 loader initializes this area to zero, and reserves the memory it 476 occupies to avoid placing boot modules and other data relevant to the 477 operating system in that area. If this field is zero, the boot loader 478 assumes that no bss segment is present. 479 480 @item entry_addr 481 The physical address to which the boot loader should jump in order to 482 start running the operating system. 483 @end table 484 485 486 @node Header graphics fields 487 @subsection The graphics fields of Multiboot header 488 489 All of the graphics fields are enabled by flag bit 2. They specify the 490 preferred graphics mode. Note that that is only a @emph{recommended} 491 mode by the OS image. If the mode exists, the boot loader should set 492 it, when the user doesn't specify a mode explicitly. Otherwise, the 493 boot loader should fall back to a similar mode, if available. 494 495 The meaning of each is as follows: 496 497 @table @code 498 @item mode_type 499 Contains @samp{0} for linear graphics mode or @samp{1} for 500 EGA-standard text mode. Everything else is reserved for future 501 expansion. Note that the boot loader may set a text mode, even if this 502 field contains @samp{0}. 503 504 @item width 505 Contains the number of the columns. This is specified in pixels in a 506 graphics mode, and in characters in a text mode. The value zero 507 indicates that the OS image has no preference. 508 509 @item height 510 Contains the number of the lines. This is specified in pixels in a 511 graphics mode, and in characters in a text mode. The value zero 512 indicates that the OS image has no preference. 513 514 @item depth 515 Contains the number of bits per pixel in a graphics mode, and zero in 516 a text mode. The value zero indicates that the OS image has no 517 preference. 518 @end table 519 520 521 @node Machine state 522 @section Machine state 523 524 When the boot loader invokes the 32-bit operating system, the machine 525 must have the following state: 526 527 @table @samp 528 @item EAX 529 Must contain the magic value @samp{0x2BADB002}; the presence of this 530 value indicates to the operating system that it was loaded by a 531 Multiboot-compliant boot loader (e.g. as opposed to another type of 532 boot loader that the operating system can also be loaded from). 533 534 @item EBX 535 Must contain the 32-bit physical address of the Multiboot 536 information structure provided by the boot loader (@pxref{Boot 537 information format}). 538 539 @item CS 540 Must be a 32-bit read/execute code segment with an offset of @samp{0} 541 and a limit of @samp{0xFFFFFFFF}. The exact value is undefined. 542 543 @item DS 544 @itemx ES 545 @itemx FS 546 @itemx GS 547 @itemx SS 548 Must be a 32-bit read/write data segment with an offset of @samp{0} 549 and a limit of @samp{0xFFFFFFFF}. The exact values are all undefined. 550 551 @item A20 gate 552 Must be enabled. 553 554 @item CR0 555 Bit 31 (PG) must be cleared. Bit 0 (PE) must be set. Other bits are 556 all undefined. 557 558 @item EFLAGS 559 Bit 17 (VM) must be cleared. Bit 9 (IF) must be cleared. Other bits 560 are all undefined. 561 @end table 562 563 All other processor registers and flag bits are undefined. This 564 includes, in particular: 565 566 @table @samp 567 @item ESP 568 The OS image must create its own stack as soon as it needs one. 569 570 @item GDTR 571 Even though the segment registers are set up as described above, the 572 @samp{GDTR} may be invalid, so the OS image must not load any segment 573 registers (even just reloading the same values!) until it sets up its 574 own @samp{GDT}. 575 576 @item IDTR 577 The OS image must leave interrupts disabled until it sets up its own 578 @code{IDT}. 579 @end table 580 581 However, other machine state should be left by the boot loader in 582 @dfn{normal working order}, i.e. as initialized by the @sc{bios} (or 583 DOS, if that's what the boot loader runs from). In other words, the 584 operating system should be able to make @sc{bios} calls and such after 585 being loaded, as long as it does not overwrite the @sc{bios} data 586 structures before doing so. Also, the boot loader must leave the 587 @sc{pic} programmed with the normal @sc{bios}/DOS values, even if it 588 changed them during the switch to 32-bit mode. 589 590 591 @node Boot information format 592 @section Boot information format 593 594 FIXME: Split this chapter like the chapter ``OS image format''. 595 596 Upon entry to the operating system, the @code{EBX} register contains the 597 physical address of a @dfn{Multiboot information} data structure, 598 through which the boot loader communicates vital information to the 599 operating system. The operating system can use or ignore any parts of 600 the structure as it chooses; all information passed by the boot loader 601 is advisory only. 602 603 The Multiboot information structure and its related substructures may be 604 placed anywhere in memory by the boot loader (with the exception of the 605 memory reserved for the kernel and boot modules, of course). It is the 606 operating system's responsibility to avoid overwriting this memory until 607 it is done using it. 608 609 The format of the Multiboot information structure (as defined so far) 610 follows: 611 612 @example 613 @group 614 +-------------------+ 615 0 | flags | (required) 616 +-------------------+ 617 4 | mem_lower | (present if flags[0] is set) 618 8 | mem_upper | (present if flags[0] is set) 619 +-------------------+ 620 12 | boot_device | (present if flags[1] is set) 621 +-------------------+ 622 16 | cmdline | (present if flags[2] is set) 623 +-------------------+ 624 20 | mods_count | (present if flags[3] is set) 625 24 | mods_addr | (present if flags[3] is set) 626 +-------------------+ 627 28 - 40 | syms | (present if flags[4] or 628 | | flags[5] is set) 629 +-------------------+ 630 44 | mmap_length | (present if flags[6] is set) 631 48 | mmap_addr | (present if flags[6] is set) 632 +-------------------+ 633 52 | drives_length | (present if flags[7] is set) 634 56 | drives_addr | (present if flags[7] is set) 635 +-------------------+ 636 60 | config_table | (present if flags[8] is set) 637 +-------------------+ 638 64 | boot_loader_name | (present if flags[9] is set) 639 +-------------------+ 640 68 | apm_table | (present if flags[10] is set) 641 +-------------------+ 642 72 | vbe_control_info | (present if flags[11] is set) 643 76 | vbe_mode_info | 644 80 | vbe_mode | 645 82 | vbe_interface_seg | 646 84 | vbe_interface_off | 647 86 | vbe_interface_len | 648 +-------------------+ 649 @end group 650 @end example 651 652 The first longword indicates the presence and validity of other fields 653 in the Multiboot information structure. All as-yet-undefined bits must 654 be set to zero by the boot loader. Any set bits that the operating 655 system does not understand should be ignored. Thus, the @samp{flags} 656 field also functions as a version indicator, allowing the Multiboot 657 information structure to be expanded in the future without breaking 658 anything. 659 660 If bit 0 in the @samp{flags} word is set, then the @samp{mem_*} fields 661 are valid. @samp{mem_lower} and @samp{mem_upper} indicate the amount of 662 lower and upper memory, respectively, in kilobytes. Lower memory starts 663 at address 0, and upper memory starts at address 1 megabyte. The maximum 664 possible value for lower memory is 640 kilobytes. The value returned for 665 upper memory is maximally the address of the first upper memory hole 666 minus 1 megabyte. It is not guaranteed to be this value. 667 668 If bit 1 in the @samp{flags} word is set, then the @samp{boot_device} 669 field is valid, and indicates which @sc{bios} disk device the boot 670 loader loaded the OS image from. If the OS image was not loaded from a 671 @sc{bios} disk, then this field must not be present (bit 3 must be 672 clear). The operating system may use this field as a hint for 673 determining its own @dfn{root} device, but is not required to. The 674 @samp{boot_device} field is laid out in four one-byte subfields as 675 follows: 676 677 @example 678 @group 679 +-------+-------+-------+-------+ 680 | drive | part1 | part2 | part3 | 681 +-------+-------+-------+-------+ 682 @end group 683 @end example 684 685 The first byte contains the @sc{bios} drive number as understood by the 686 @sc{bios} INT 0x13 low-level disk interface: e.g. 0x00 for the first 687 floppy disk or 0x80 for the first hard disk. 688 689 The three remaining bytes specify the boot partition. @samp{part1} 690 specifies the @dfn{top-level} partition number, @samp{part2} specifies a 691 @dfn{sub-partition} in the top-level partition, etc. Partition numbers 692 always start from zero. Unused partition bytes must be set to 0xFF. For 693 example, if the disk is partitioned using a simple one-level DOS 694 partitioning scheme, then @samp{part1} contains the DOS partition 695 number, and @samp{part2} and @samp{part3} are both 0xFF. As another 696 example, if a disk is partitioned first into DOS partitions, and then 697 one of those DOS partitions is subdivided into several BSD partitions 698 using BSD's @dfn{disklabel} strategy, then @samp{part1} contains the DOS 699 partition number, @samp{part2} contains the BSD sub-partition within 700 that DOS partition, and @samp{part3} is 0xFF. 701 702 DOS extended partitions are indicated as partition numbers starting from 703 4 and increasing, rather than as nested sub-partitions, even though the 704 underlying disk layout of extended partitions is hierarchical in 705 nature. For example, if the boot loader boots from the second extended 706 partition on a disk partitioned in conventional DOS style, then 707 @samp{part1} will be 5, and @samp{part2} and @samp{part3} will both be 708 0xFF. 709 710 If bit 2 of the @samp{flags} longword is set, the @samp{cmdline} field 711 is valid, and contains the physical address of the command line to 712 be passed to the kernel. The command line is a normal C-style 713 zero-terminated string. 714 715 If bit 3 of the @samp{flags} is set, then the @samp{mods} fields 716 indicate to the kernel what boot modules were loaded along with the 717 kernel image, and where they can be found. @samp{mods_count} contains 718 the number of modules loaded; @samp{mods_addr} contains the physical 719 address of the first module structure. @samp{mods_count} may be zero, 720 indicating no boot modules were loaded, even if bit 1 of @samp{flags} is 721 set. Each module structure is formatted as follows: 722 723 @example 724 @group 725 +-------------------+ 726 0 | mod_start | 727 4 | mod_end | 728 +-------------------+ 729 8 | string | 730 +-------------------+ 731 12 | reserved (0) | 732 +-------------------+ 733 @end group 734 @end example 735 736 The first two fields contain the start and end addresses of the boot 737 module itself. The @samp{string} field provides an arbitrary string to 738 be associated with that particular boot module; it is a zero-terminated 739 ASCII string, just like the kernel command line. The @samp{string} field 740 may be 0 if there is no string associated with the module. Typically the 741 string might be a command line (e.g. if the operating system treats boot 742 modules as executable programs), or a pathname (e.g. if the operating 743 system treats boot modules as files in a file system), but its exact use 744 is specific to the operating system. The @samp{reserved} field must be 745 set to 0 by the boot loader and ignored by the operating system. 746 747 @strong{Caution:} Bits 4 & 5 are mutually exclusive. 748 749 If bit 4 in the @samp{flags} word is set, then the following fields in 750 the Multiboot information structure starting at byte 28 are valid: 751 752 @example 753 @group 754 +-------------------+ 755 28 | tabsize | 756 32 | strsize | 757 36 | addr | 758 40 | reserved (0) | 759 +-------------------+ 760 @end group 761 @end example 762 763 These indicate where the symbol table from an a.out kernel image can be 764 found. @samp{addr} is the physical address of the size (4-byte unsigned 765 long) of an array of a.out format @dfn{nlist} structures, followed 766 immediately by the array itself, then the size (4-byte unsigned long) of 767 a set of zero-terminated @sc{ascii} strings (plus sizeof(unsigned long) in 768 this case), and finally the set of strings itself. @samp{tabsize} is 769 equal to its size parameter (found at the beginning of the symbol 770 section), and @samp{strsize} is equal to its size parameter (found at 771 the beginning of the string section) of the following string table to 772 which the symbol table refers. Note that @samp{tabsize} may be 0, 773 indicating no symbols, even if bit 4 in the @samp{flags} word is set. 774 775 If bit 5 in the @samp{flags} word is set, then the following fields in 776 the Multiboot information structure starting at byte 28 are valid: 777 778 @example 779 @group 780 +-------------------+ 781 28 | num | 782 32 | size | 783 36 | addr | 784 40 | shndx | 785 +-------------------+ 786 @end group 787 @end example 788 789 These indicate where the section header table from an ELF kernel is, the 790 size of each entry, number of entries, and the string table used as the 791 index of names. They correspond to the @samp{shdr_*} entries 792 (@samp{shdr_num}, etc.) in the Executable and Linkable Format (@sc{elf}) 793 specification in the program header. All sections are loaded, and the 794 physical address fields of the @sc{elf} section header then refer to where 795 the sections are in memory (refer to the i386 @sc{elf} documentation for 796 details as to how to read the section header(s)). Note that 797 @samp{shdr_num} may be 0, indicating no symbols, even if bit 5 in the 798 @samp{flags} word is set. 799 800 If bit 6 in the @samp{flags} word is set, then the @samp{mmap_*} fields 801 are valid, and indicate the address and length of a buffer containing a 802 memory map of the machine provided by the @sc{bios}. @samp{mmap_addr} is 803 the address, and @samp{mmap_length} is the total size of the buffer. The 804 buffer consists of one or more of the following size/structure pairs 805 (@samp{size} is really used for skipping to the next pair): 806 807 @example 808 @group 809 +-------------------+ 810 -4 | size | 811 +-------------------+ 812 0 | base_addr_low | 813 4 | base_addr_high | 814 8 | length_low | 815 12 | length_high | 816 16 | type | 817 +-------------------+ 818 @end group 819 @end example 820 821 where @samp{size} is the size of the associated structure in bytes, which 822 can be greater than the minimum of 20 bytes. @samp{base_addr_low} is the 823 lower 32 bits of the starting address, and @samp{base_addr_high} is the 824 upper 32 bits, for a total of a 64-bit starting address. @samp{length_low} 825 is the lower 32 bits of the size of the memory region in bytes, and 826 @samp{length_high} is the upper 32 bits, for a total of a 64-bit 827 length. @samp{type} is the variety of address range represented, where a 828 value of 1 indicates available @sc{ram}, and all other values currently 829 indicated a reserved area. 830 831 The map provided is guaranteed to list all standard @sc{ram} that should 832 be available for normal use. 833 834 If bit 7 in the @samp{flags} is set, then the @samp{drives_*} fields 835 are valid, and indicate the address of the physical address of the first 836 drive structure and the size of drive structures. @samp{drives_addr} 837 is the address, and @samp{drives_length} is the total size of drive 838 structures. Note that @samp{drives_length} may be zero. Each drive 839 structure is formatted as follows: 840 841 @example 842 @group 843 +-------------------+ 844 0 | size | 845 +-------------------+ 846 4 | drive_number | 847 +-------------------+ 848 5 | drive_mode | 849 +-------------------+ 850 6 | drive_cylinders | 851 8 | drive_heads | 852 9 | drive_sectors | 853 +-------------------+ 854 10 - xx | drive_ports | 855 +-------------------+ 856 @end group 857 @end example 858 859 The @samp{size} field specifies the size of this structure. The size 860 varies, depending on the number of ports. Note that the size may not be 861 equal to (10 + 2 * the number of ports), because of an alignment. 862 863 The @samp{drive_number} field contains the BIOS drive number. The 864 @samp{drive_mode} field represents the access mode used by the boot 865 loader. Currently, the following modes are defined: 866 867 @table @samp 868 @item 0 869 CHS mode (traditional cylinder/head/sector addressing mode). 870 871 @item 1 872 LBA mode (Logical Block Addressing mode). 873 @end table 874 875 The three fields, @samp{drive_cylinders}, @samp{drive_heads} and 876 @samp{drive_sectors}, indicate the geometry of the drive detected by the 877 @sc{bios}. @samp{drive_cylinders} contains the number of the 878 cylinders. @samp{drive_heads} contains the number of the 879 heads. @samp{drive_sectors} contains the number of the sectors per 880 track. 881 882 The @samp{drive_ports} field contains the array of the I/O ports used 883 for the drive in the @sc{bios} code. The array consists of zero or more 884 unsigned two-bytes integers, and is terminated with zero. Note that the 885 array may contain any number of I/O ports that are not related to the 886 drive actually (such as @sc{dma} controller's ports). 887 888 If bit 8 in the @samp{flags} is set, then the @samp{config_table} field 889 is valid, and indicates the address of the @sc{rom} configuration table 890 returned by the @dfn{GET CONFIGURATION} @sc{bios} call. If the @sc{bios} 891 call fails, then the size of the table must be @emph{zero}. 892 893 If bit 9 in the @samp{flags} is set, the @samp{boot_loader_name} field 894 is valid, and contains the physical address of the name of a boot 895 loader booting the kernel. The name is a normal C-style zero-terminated 896 string. 897 898 If bit 10 in the @samp{flags} is set, the @samp{apm_table} field is 899 valid, and contains the physical address of an @sc{apm} table defined as 900 below: 901 902 @example 903 @group 904 +----------------------+ 905 0 | version | 906 2 | cseg | 907 4 | offset | 908 8 | cseg_16 | 909 10 | dseg | 910 12 | flags | 911 14 | cseg_len | 912 16 | cseg_16_len | 913 18 | dseg_len | 914 +----------------------+ 915 @end group 916 @end example 917 918 The fields @samp{version}, @samp{cseg}, @samp{offset}, @samp{cseg_16}, 919 @samp{dseg}, @samp{flags}, @samp{cseg_len}, @samp{cseg_16_len}, 920 @samp{dseg_len} indicate the version number, the protected mode 32-bit 921 code segment, the offset of the entry point, the protected mode 16-bit 922 code segment, the protected mode 16-bit data segment, the flags, the 923 length of the protected mode 32-bit code segment, the length of the 924 protected mode 16-bit code segment, and the length of the protected mode 925 16-bit data segment, respectively. Only the field @samp{offset} is 4 926 bytes, and the others are 2 bytes. See 927 @uref{http://www.microsoft.com/hwdev/busbios/amp_12.htm, Advanced Power 928 Management (APM) BIOS Interface Specification}, for more information. 929 930 If bit 11 in the @samp{flags} is set, the graphics table is available. 931 This must only be done if the kernel has indicated in the 932 @samp{Multiboot Header} that it accepts a graphics mode. 933 934 The fields @samp{vbe_control_info} and @samp{vbe_mode_info} contain 935 the physical addresses of @sc{vbe} control information returned by the 936 @sc{vbe} Function 00h and @sc{vbe} mode information returned by the 937 @sc{vbe} Function 01h, respectively. 938 939 The field @samp{vbe_mode} indicates current video mode in the format 940 specified in @sc{vbe} 3.0. 941 942 The rest fields @samp{vbe_interface_seg}, @samp{vbe_interface_off}, and 943 @samp{vbe_interface_len} contain the table of a protected mode interface 944 defined in @sc{vbe} 2.0+. If this information is not available, those 945 fields contain zero. Note that @sc{vbe} 3.0 defines another protected 946 mode interface which is incompatible with the old one. If you want to 947 use the new protected mode interface, you will have to find the table 948 yourself. 949 950 The fields for the graphics table are designed for @sc{vbe}, but 951 Multiboot boot loaders may simulate @sc{vbe} on non-@sc{vbe} modes, as 952 if they were @sc{vbe} modes. 953 954 955 @node Examples 956 @chapter Examples 957 958 @strong{Caution:} The following items are not part of the specification 959 document, but are included for prospective operating system and boot 960 loader writers. 961 962 @menu 963 * Notes on PC:: 964 * BIOS device mapping techniques:: 965 * Example OS code:: 966 * Example boot loader code:: 967 @end menu 968 969 970 @node Notes on PC 971 @section Notes on PC 972 973 In reference to bit 0 of the @samp{flags} parameter in the Multiboot 974 information structure, if the bootloader in question uses older 975 @sc{bios} interfaces, or the newest ones are not available (see 976 description about bit 6), then a maximum of either 15 or 63 megabytes of 977 memory may be reported. It is @emph{highly} recommended that boot 978 loaders perform a thorough memory probe. 979 980 In reference to bit 1 of the @samp{flags} parameter in the Multiboot 981 information structure, it is recognized that determination of which 982 @sc{bios} drive maps to which device driver in an operating system is 983 non-trivial, at best. Many kludges have been made to various operating 984 systems instead of solving this problem, most of them breaking under 985 many conditions. To encourage the use of general-purpose solutions to 986 this problem, there are 2 @sc{bios} device mapping techniques 987 (@pxref{BIOS device mapping techniques}). 988 989 In reference to bit 6 of the @samp{flags} parameter in the Multiboot 990 information structure, it is important to note that the data structure 991 used there (starting with @samp{BaseAddrLow}) is the data returned by 992 the INT 15h, AX=E820h --- Query System Address Map call. See @xref{Query 993 System Address Map, , Query System Address Map, grub.info, The GRUB 994 Manual}, for more information. The interface here is meant to allow a 995 boot loader to work unmodified with any reasonable extensions of the 996 @sc{bios} interface, passing along any extra data to be interpreted by 997 the operating system as desired. 998 999 1000 @node BIOS device mapping techniques 1001 @section BIOS device mapping techniques 1002 1003 Both of these techniques should be usable from any PC operating system, 1004 and neither require any special support in the drivers themselves. This 1005 section will be flushed out into detailed explanations, particularly for 1006 the I/O restriction technique. 1007 1008 The general rule is that the data comparison technique is the quick and 1009 dirty solution. It works most of the time, but doesn't cover all the 1010 bases, and is relatively simple. 1011 1012 The I/O restriction technique is much more complex, but it has potential 1013 to solve the problem under all conditions, plus allow access of the 1014 remaining @sc{bios} devices when not all of them have operating system 1015 drivers. 1016 1017 @menu 1018 * Data comparison technique:: 1019 * I/O restriction technique:: 1020 @end menu 1021 1022 1023 @node Data comparison technique 1024 @subsection Data comparison technique 1025 1026 Before activating @emph{any} of the device drivers, gather enough data 1027 from similar sectors on each of the disks such that each one can be 1028 uniquely identified. 1029 1030 After activating the device drivers, compare data from the drives using 1031 the operating system drivers. This should hopefully be sufficient to 1032 provide such a mapping. 1033 1034 Problems: 1035 1036 @enumerate 1037 @item 1038 The data on some @sc{bios} devices might be identical (so the part 1039 reading the drives from the @sc{bios} should have some mechanism to give 1040 up). 1041 1042 @item 1043 There might be extra drives not accessible from the @sc{bios} which are 1044 identical to some drive used by the @sc{bios} (so it should be capable 1045 of giving up there as well). 1046 @end enumerate 1047 1048 1049 @node I/O restriction technique 1050 @subsection I/O restriction technique 1051 1052 This first step may be unnecessary, but first create copy-on-write 1053 mappings for the device drivers writing into @sc{pc} @sc{ram}. Keep the 1054 original copies for the @dfn{clean @sc{bios} virtual machine} to be 1055 created later. 1056 1057 For each device driver brought online, determine which @sc{bios} devices 1058 become inaccessible by: 1059 1060 @enumerate 1061 @item 1062 Create a @dfn{clean @sc{bios} virtual machine}. 1063 1064 @item 1065 Set the I/O permission map for the I/O area claimed by the device driver 1066 to no permissions (neither read nor write). 1067 1068 @item 1069 Access each device. 1070 1071 @item 1072 Record which devices succeed, and those which try to access the 1073 @dfn{restricted} I/O areas (hopefully, this will be an @dfn{xor} 1074 situation). 1075 @end enumerate 1076 1077 For each device driver, given how many of the @sc{bios} devices were 1078 subsumed by it (there should be no gaps in this list), it should be easy 1079 to determine which devices on the controller these are. 1080 1081 In general, you have at most 2 disks from each controller given 1082 @sc{bios} numbers, but they pretty much always count from the lowest 1083 logically numbered devices on the controller. 1084 1085 1086 @node Example OS code 1087 @section Example OS code 1088 1089 In this distribution, the example Multiboot kernel @file{kernel} is 1090 included. The kernel just prints out the Multiboot information structure 1091 on the screen, so you can make use of the kernel to test a 1092 Multiboot-compliant boot loader and for reference to how to implement a 1093 Multiboot kernel. The source files can be found under the directory 1094 @file{docs} in the GRUB distribution. 1095 1096 The kernel @file{kernel} consists of only three files: @file{boot.S}, 1097 @file{kernel.c} and @file{multiboot.h}. The assembly source 1098 @file{boot.S} is written in GAS (@pxref{Top, , GNU assembler, as.info, 1099 The GNU assembler}), and contains the Multiboot information structure to 1100 comply with the specification. When a Multiboot-compliant boot loader 1101 loads and execute it, it initialize the stack pointer and @code{EFLAGS}, 1102 and then call the function @code{cmain} defined in @file{kernel.c}. If 1103 @code{cmain} returns to the callee, then it shows a message to inform 1104 the user of the halt state and stops forever until you push the reset 1105 key. The file @file{kernel.c} contains the function @code{cmain}, 1106 which checks if the magic number passed by the boot loader is valid and 1107 so on, and some functions to print messages on the screen. The file 1108 @file{multiboot.h} defines some macros, such as the magic number for the 1109 Multiboot header, the Multiboot header structure and the Multiboot 1110 information structure. 1111 1112 @menu 1113 * multiboot.h:: 1114 * boot.S:: 1115 * kernel.c:: 1116 * Other Multiboot kernels:: 1117 @end menu 1118 1119 1120 @node multiboot.h 1121 @subsection multiboot.h 1122 1123 This is the source code in the file @file{multiboot.h}: 1124 1125 @example 1126 @include multiboot.h.texi 1127 @end example 1128 1129 1130 @node boot.S 1131 @subsection boot.S 1132 1133 In the file @file{boot.S}: 1134 1135 @example 1136 @include boot.S.texi 1137 @end example 1138 1139 1140 @node kernel.c 1141 @subsection kernel.c 1142 1143 And, in the file @file{kernel.c}: 1144 1145 @example 1146 @include kernel.c.texi 1147 @end example 1148 1149 1150 @node Other Multiboot kernels 1151 @subsection Other Multiboot kernels 1152 1153 Other useful information should be available in Multiboot kernels, such 1154 as GNU Mach and Fiasco @url{http://os.inf.tu-dresden.de/fiasco/}. And, 1155 it is worth mentioning the OSKit 1156 @url{http://www.cs.utah.edu/projects/flux/oskit/}, which provides a 1157 library supporting the specification. 1158 1159 1160 @node Example boot loader code 1161 @section Example boot loader code 1162 1163 The GNU GRUB (@pxref{Top, , GRUB, grub.info, The GRUB manual}) project 1164 is a full Multiboot-compliant boot loader, supporting all required and 1165 optional features present in this specification. A public release has 1166 not been made, but the test release is available from: 1167 1168 @url{ftp://alpha.gnu.org/gnu/grub} 1169 1170 See the webpage @url{http://www.gnu.org/software/grub/grub.html}, for 1171 more information. 1172 1173 1174 @node History 1175 @chapter The change log of this specification 1176 1177 @table @asis 1178 @item 0.7 1179 @itemize @bullet 1180 @item 1181 @dfn{Multiboot Standard} is renamed to @dfn{Multiboot Specification}. 1182 1183 @item 1184 Graphics fields are added to Multiboot header. 1185 1186 @item 1187 BIOS drive information, BIOS configuration table, the name of a boot 1188 loader, APM information, and graphics information are added to Multiboot 1189 information. 1190 1191 @item 1192 Rewritten in Texinfo format. 1193 1194 @item 1195 Rewritten, using more strict words. 1196 1197 @item 1198 The maintainer changes to the GNU GRUB maintainer team 1199 @email{bug-grub@@gnu.org}, from Bryan Ford and Erich Stefan Boleyn. 1200 @end itemize 1201 1202 @item 0.6 1203 @itemize @bullet 1204 @item 1205 A few wording changes. 1206 1207 @item 1208 Header checksum. 1209 1210 @item 1211 Clasification of machine state passed to an operating system. 1212 @end itemize 1213 1214 @item 0.5 1215 @itemize @bullet 1216 @item 1217 Name change. 1218 @end itemize 1219 1220 @item 0.4 1221 @itemize @bullet 1222 @item 1223 Major changes plus HTMLification. 1224 @end itemize 1225 @end table 1226 1227 1228 @node Index 1229 @unnumbered Index 1230 1231 @printindex cp 1232 1233 @contents 1234 @bye 1235
