Lines Matching refs:the

31 this manual provided the copyright notice and this permission notice
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).
43 manual under the conditions for verbatim copying, provided also that
44 the entire resulting derived work is distributed under the terms of a
48 into another language, under the above conditions for modified versions.
63 this manual provided the copyright notice and this permission notice
67 manual under the conditions for verbatim copying, provided also that
68 the entire resulting derived work is distributed under the terms of a
72 into another language, under the above conditions for modified versions.
82 This file documents Multiboot Specification, the proposal for the boot
99 This chapter describes some rough information on the Multiboot
100 Specification. Note that this is not a part of the specification itself.
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,
127 operating systems, it shouldn't be too difficult for a few people in the
129 this problem for the popular free operating systems. That's what this
134 only how they must interface with the operating system being loaded.
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
144 this specification, stripped of the x86-specific details, could be
152 that can be fairly easily modified to support the specification without
156 emerging free operating systems will adopt it from the start, and thus
165 It should be possible to write compliant boot loaders that load the OS
169 Disk-based boot loaders may use a variety of techniques to find the
171 interpretation of specific file systems (e.g. the BSD/Mach boot loader),
174 another operating system (e.g. the VSTa boot code, which loads from
186 It is often necessary for one reason or another for the user to be able
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.
198 be an ordinary 32-bit executable file in whatever file format the
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
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
215 a different format for each operating system. Most of the relevant free
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
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
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
236 not by themselves contain enough mechanism to get the system fully
237 operational: they require the presence of additional software modules at
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.
247 loader to indicate to the operating system what auxiliary boot modules
254 @chapter The definitions of terms used through the specification
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}
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.
267 We use the term @dfn{may}, when any boot loader or OS image is allowed
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
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
283 typically an executable containing the operating system kernel.
288 locations to the operating system when it is invoked.
291 A boot loader or an OS image which follows the rules defined as
294 image doesn't need to follow the rule.
300 The type of unsigned 16-bit data. Because the target architecture is
304 The type of unsigned 32-bit data. Because the target architecture is
308 The type of unsigned 64-bit data. Because the target architecture is
341 An OS image may be an ordinary 32-bit executable file in the standard
343 linked at a non-default load address to avoid loading on top of the
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
352 embedded in the beginning of the text segment after the @emph{real}
366 The layout of the Multiboot header must be as follows:
385 @ref{Header magic fields}, the fields @samp{header_addr},
387 @samp{entry_addr} are defined in @ref{Header address fields}, and the
397 The field @samp{magic} is the magic number identifying the header,
398 which must be the hexadecimal value @code{0x1BADB002}.
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
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
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
416 startup, and thus need the boot modules to be page-aligned.
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)
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
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
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
441 to the other magic fields (i.e. @samp{magic} and @samp{flags}), must
449 All of the address fields enabled by flag bit 16 are physical addresses.
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
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 -
466 Contains the physical address of the end of the data
468 This implies that the text and data segments must be consecutive in the
470 If this field is zero, the boot loader assumes that the text and data
471 segments occupy the whole OS image file.
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
481 The physical address to which the boot loader should jump in order to
482 start running the operating system.
489 All of the graphics fields are enabled by flag bit 2. They specify the
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
501 expansion. Note that the boot loader may set a text mode, even if this
505 Contains the number of the columns. This is specified in pixels in a
507 indicates that the OS image has no preference.
510 Contains the number of the lines. This is specified in pixels in a
512 indicates that the OS image has no preference.
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
524 When the boot loader invokes the 32-bit operating system, the machine
525 must have the following state:
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
532 boot loader that the operating system can also be loaded from).
535 Must contain the 32-bit physical address of the Multiboot
536 information structure provided by the boot loader (@pxref{Boot
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
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
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.
594 FIXME: Split this chapter like the chapter ``OS image format''.
596 Upon entry to the operating system, the @code{EBX} register contains the
598 through which the boot loader communicates vital information to the
600 the structure as it chooses; all information passed by the boot loader
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
609 The format of the Multiboot information structure (as defined so far)
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
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
665 upper memory is maximally the address of the first upper memory hole
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
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.
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
693 example, if the disk is partitioned using a simple one-level DOS
694 partitioning scheme, then @samp{part1} contains the DOS partition
698 using BSD's @dfn{disklabel} strategy, then @samp{part1} contains the DOS
699 partition number, @samp{part2} contains the BSD sub-partition within
703 4 and increasing, rather than as nested sub-partitions, even though the
705 nature. For example, if the boot loader boots from the second extended
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
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
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,
736 The first two fields contain the start and end addresses of the boot
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
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.
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:
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
766 immediately by the array itself, then the size (4-byte unsigned long) of
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
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.
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:
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
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):
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
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
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
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.
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:
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
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
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}.
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
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
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
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
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
939 The field @samp{vbe_mode} indicates current video mode in the format
943 @samp{vbe_interface_len} contain the table of a protected mode interface
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
950 The fields for the graphics table are designed for @sc{vbe}, but
958 @strong{Caution:} The following items are not part of the specification
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
980 In reference to bit 1 of the @samp{flags} parameter in the Multiboot
985 many conditions. To encourage the use of general-purpose solutions to
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
995 boot loader to work unmodified with any reasonable extensions of the
997 the operating system as desired.
1004 and neither require any special support in the drivers themselves. This
1006 the I/O restriction technique.
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
1013 to solve the problem under all conditions, plus allow access of the
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
1030 After activating the device drivers, compare data from the drives using
1031 the operating system drivers. This should hopefully be sufficient to
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
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
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
1065 Set the I/O permission map for the I/O area claimed by the device driver
1072 Record which devices succeed, and those which try to access the
1077 For each device driver, given how many of the @sc{bios} devices were
1079 to determine which devices on the controller these are.
1082 @sc{bios} numbers, but they pretty much always count from the lowest
1083 logically numbered devices on the controller.
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
1093 Multiboot kernel. The source files can be found under the directory
1094 @file{docs} in the GRUB distribution.
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
1123 This is the source code in the file @file{multiboot.h}:
1133 In the file @file{boot.S}:
1143 And, in the file @file{kernel.c}:
1155 it is worth mentioning the OSKit
1157 library supporting the specification.
1166 not been made, but the test release is available from:
1170 See the webpage @url{http://www.gnu.org/software/grub/grub.html}, for
1187 BIOS drive information, BIOS configuration table, the name of a boot
1198 The maintainer changes to the GNU GRUB maintainer team