Lines Matching refs:the
14 manual provided the copyright notice and this permission notice are
18 this manual under the conditions for verbatim copying, provided also
19 that the entire resulting derived work is distributed under the terms
23 manual into another language, under the above conditions for modified
32 This file documents Multiboot Specification, the proposal for the boot
50 This chapter describes some rough information on the Multiboot
51 Specification. Note that this is not a part of the specification itself.
75 of boot loaders for a particular operating system -- if the one that
76 comes with the operating system doesn't do exactly what you want, or
80 operating systems, it shouldn't be too difficult for a few people in the
82 this problem for the popular free operating systems. That's what this
87 how they must interface with the operating system being loaded.
95 This specification is primarily targeted at PC, since they are the most
96 common and have the largest variety of operating systems and boot
97 loaders. However, to the extent that certain other architectures may
99 this specification, stripped of the x86-specific details, could be
109 that can be fairly easily modified to support the specification without
113 emerging free operating systems will adopt it from the start, and thus
124 It should be possible to write compliant boot loaders that load the OS
128 Disk-based boot loaders may use a variety of techniques to find the
130 interpretation of specific file systems (e.g. the BSD/Mach boot loader),
133 operating system (e.g. the VSTa boot code, which loads from DOS).
147 It is often necessary for one reason or another for the user to be able
150 how this configuration information is obtained by the boot loader, it
151 should provide a standard means for the boot loader to pass such
152 information to the operating system.
161 be an ordinary 32-bit executable file in whatever file format the
165 If this means shifting some work from the operating system to a boot
166 loader, that is probably appropriate, because all the memory consumed
167 by the boot loader will typically be made available again after the
168 boot process is created, whereas every bit of code in the OS image
171 switching code generally needs to be in the boot loader anyway in order
172 to load operating system data above the 1MB boundary, and forcing the
178 generally a different format for each operating system. Most of the
181 have to be able to interpret all the different types of executable file
182 formats in existence in order to load the OS image -- otherwise the
187 (*note OS image format::), which allows the boot loader to load the
189 executable formats. This magic header does not need to be at the very
190 beginning of the executable file, so kernel images can still conform to
191 the local a.out format variant in addition to being Multiboot-compliant.
200 not by themselves contain enough mechanism to get the system fully
201 operational: they require the presence of additional software modules at
203 these additional modules could be embedded in the main OS image along
204 with the kernel itself, and the resulting image be split apart manually
205 by the operating system when it receives control, it is often more
206 flexible, more space-efficient, and more convenient to the operating
207 system and user if the boot loader can load these additional modules
208 independently in the first place.
211 loader to indicate to the operating system what auxiliary boot modules
219 2 The definitions of terms used through the specification
223 We use the term "must", when any boot loader or OS image needs to
224 follow a rule -- otherwise, the boot loader or OS image is _not_
228 We use the term "should", when any boot loader or OS image is
229 recommended to follow a rule, but it doesn't need to follow the
233 We use the term "may", when any boot loader or OS image is allowed
237 Whatever program or set of programs loads the image of the final
238 operating system to be run on the machine. The boot loader may
240 detail not relevant to this specification. Only the _final_ stage
241 of the boot loader -- the stage that eventually transfers control
242 to an operating system -- must follow the rules specified in this
249 typically an executable containing the operating system kernel.
254 passing their locations to the operating system when it is invoked.
257 A boot loader or an OS image which follows the rules defined as
260 image doesn't need to follow the rule.
266 The type of unsigned 16-bit data. Because the target architecture
270 The type of unsigned 32-bit data. Because the target architecture
274 The type of unsigned 64-bit data. Because the target architecture
305 An OS image may be an ordinary 32-bit executable file in the standard
307 linked at a non-default load address to avoid loading on top of the
312 header", besides the headers of the format used by the OS image. The
313 Multiboot header must be contained completely within the first 8192
314 bytes of the OS image, and must be longword (32-bit) aligned. In
316 the beginning of the text segment after the _real_ executable header.
331 The layout of the Multiboot header must be as follows:
348 Header magic fields::, the fields `header_addr', `load_addr',
350 Header address fields::, and the fields `mode_type', `width', `height'
360 The field `magic' is the magic number identifying the header,
361 which must be the hexadecimal value `0x1BADB002'.
364 The field `flags' specifies features that the OS image requests or
365 requires of an boot loader. Bits 0-15 indicate requirements; if the
366 boot loader sees any of these bits set but doesn't understand the
367 flag or can't fulfill the requirements it indicates for some
368 reason, it must notify the user and fail to load the OS image.
370 are set but the boot loader doesn't understand them, it may simply
372 bits in the `flags' word must be set to zero in OS images. This
373 way, the `flags' fields serves for version control as well as
376 If bit 0 in the `flags' word is set, then all boot modules loaded
377 along with the operating system must be aligned on page (4KB)
378 boundaries. Some operating systems expect to be able to map the
380 during startup, and thus need the boot modules to be page-aligned.
382 If bit 1 in the `flags' word is set, then information on available
383 memory via at least the `mem_*' fields of the Multiboot information
385 the boot loader is capable of passing a memory map (the `mmap_*'
388 If bit 2 in the `flags' word is set, information about the video
390 the kernel.
392 If bit 16 in the `flags' word is set, then the fields at offsets
393 8-24 in the Multiboot header are valid, and the boot loader should
394 use them instead of the fields in the actual executable header to
395 calculate where to load the OS image. This information does not
396 need to be provided if the kernel image is in ELF format, but it
397 _must_ be provided if the images is in a.out format or in some
399 that either are in ELF format or contain the load address
400 information embedded in the Multiboot header; they may also
406 to the other magic fields (i.e. `magic' and `flags'), must have a
415 All of the address fields enabled by flag bit 16 are physical addresses.
419 Contains the address corresponding to the beginning of the
420 Multiboot header -- the physical memory location at which the
422 "synchronize" the mapping between OS image offsets and physical
426 Contains the physical address of the beginning of the text
427 segment. The offset in the OS image file at which to start loading
428 is defined by the offset at which the header was found, minus
433 Contains the physical address of the end of the data segment.
435 implies that the text and data segments must be consecutive in the
437 this field is zero, the boot loader assumes that the text and data
438 segments occupy the whole OS image file.
441 Contains the physical address of the end of the bss segment. The
442 boot loader initializes this area to zero, and reserves the memory
444 to the operating system in that area. If this field is zero, the
448 The physical address to which the boot loader should jump in order
449 to start running the operating system.
457 All of the graphics fields are enabled by flag bit 2. They specify the
459 the OS image. If the mode exists, the boot loader should set it, when
460 the user doesn't specify a mode explicitly. Otherwise, the boot loader
468 the boot loader may set a text mode, even if this field contains
472 Contains the number of the columns. This is specified in pixels in
474 indicates that the OS image has no preference.
477 Contains the number of the lines. This is specified in pixels in a
479 indicates that the OS image has no preference.
482 Contains the number of bits per pixel in a graphics mode, and zero
483 in a text mode. The value zero indicates that the OS image has no
492 When the boot loader invokes the 32-bit operating system, the machine
493 must have the following state:
496 Must contain the magic value `0x2BADB002'; the presence of this
497 value indicates to the operating system that it was loaded by a
499 boot loader that the operating system can also be loaded from).
502 Must contain the 32-bit physical address of the Multiboot
503 information structure provided by the boot loader (*note Boot
536 Even though the segment registers are set up as described above,
537 the `GDTR' may be invalid, so the OS image must not load any
538 segment registers (even just reloading the same values!) until it
545 However, other machine state should be left by the boot loader in
546 "normal working order", i.e. as initialized by the BIOS (or DOS, if
547 that's what the boot loader runs from). In other words, the operating
549 as long as it does not overwrite the BIOS data structures before doing
550 so. Also, the boot loader must leave the PIC programmed with the normal
551 BIOS/DOS values, even if it changed them during the switch to 32-bit
560 FIXME: Split this chapter like the chapter "OS image format".
562 Upon entry to the operating system, the `EBX' register contains the
564 which the boot loader communicates vital information to the operating
565 system. The operating system can use or ignore any parts of the
566 structure as it chooses; all information passed by the boot loader is
570 may be placed anywhere in memory by the boot loader (with the exception
571 of the memory reserved for the kernel and boot modules, of course). It
572 is the operating system's responsibility to avoid overwriting this
575 The format of the Multiboot information structure (as defined so far)
614 The first longword indicates the presence and validity of other
615 fields in the Multiboot information structure. All as-yet-undefined
616 bits must be set to zero by the boot loader. Any set bits that the
617 operating system does not understand should be ignored. Thus, the
618 `flags' field also functions as a version indicator, allowing the
619 Multiboot information structure to be expanded in the future without
622 If bit 0 in the `flags' word is set, then the `mem_*' fields are
623 valid. `mem_lower' and `mem_upper' indicate the amount of lower and
627 upper memory is maximally the address of the first upper memory hole
630 If bit 1 in the `flags' word is set, then the `boot_device' field is
631 valid, and indicates which BIOS disk device the boot loader loaded the
632 OS image from. If the OS image was not loaded from a BIOS disk, then
642 The first byte contains the BIOS drive number as understood by the
643 BIOS INT 0x13 low-level disk interface: e.g. 0x00 for the first floppy
644 disk or 0x80 for the first hard disk.
646 The three remaining bytes specify the boot partition. `part1'
647 specifies the "top-level" partition number, `part2' specifies a
648 "sub-partition" in the top-level partition, etc. Partition numbers
650 example, if the disk is partitioned using a simple one-level DOS
651 partitioning scheme, then `part1' contains the DOS partition number,
655 "disklabel" strategy, then `part1' contains the DOS partition number,
656 `part2' contains the BSD sub-partition within that DOS partition, and
661 though the underlying disk layout of extended partitions is
662 hierarchical in nature. For example, if the boot loader boots from the
667 If bit 2 of the `flags' longword is set, the `cmdline' field is
668 valid, and contains the physical address of the command line to be
669 passed to the kernel. The command line is a normal C-style
672 If bit 3 of the `flags' is set, then the `mods' fields indicate to
673 the kernel what boot modules were loaded along with the kernel image,
674 and where they can be found. `mods_count' contains the number of
675 modules loaded; `mods_addr' contains the physical address of the first
689 The first two fields contain the start and end addresses of the boot
692 ASCII string, just like the kernel command line. The `string' field may
693 be 0 if there is no string associated with the module. Typically the
694 string might be a command line (e.g. if the operating system treats boot
695 modules as executable programs), or a pathname (e.g. if the operating
697 is specific to the operating system. The `reserved' field must be set
698 to 0 by the boot loader and ignored by the operating system.
702 If bit 4 in the `flags' word is set, then the following fields in
703 the Multiboot information structure starting at byte 28 are valid:
712 These indicate where the symbol table from an a.out kernel image can
713 be found. `addr' is the physical address of the size (4-byte unsigned
715 immediately by the array itself, then the size (4-byte unsigned long) of
717 this case), and finally the set of strings itself. `tabsize' is equal
718 to its size parameter (found at the beginning of the symbol section),
719 and `strsize' is equal to its size parameter (found at the beginning of
720 the string section) of the following string table to which the symbol
722 if bit 4 in the `flags' word is set.
724 If bit 5 in the `flags' word is set, then the following fields in
725 the Multiboot information structure starting at byte 28 are valid:
734 These indicate where the section header table from an ELF kernel is,
735 the size of each entry, number of entries, and the string table used as
736 the index of names. They correspond to the `shdr_*' entries
737 (`shdr_num', etc.) in the Executable and Linkable Format (ELF)
738 specification in the program header. All sections are loaded, and the
739 physical address fields of the ELF section header then refer to where
740 the sections are in memory (refer to the i386 ELF documentation for
741 details as to how to read the section header(s)). Note that `shdr_num'
742 may be 0, indicating no symbols, even if bit 5 in the `flags' word is
745 If bit 6 in the `flags' word is set, then the `mmap_*' fields are
746 valid, and indicate the address and length of a buffer containing a
747 memory map of the machine provided by the BIOS. `mmap_addr' is the
748 address, and `mmap_length' is the total size of the buffer. The buffer
749 consists of one or more of the following size/structure pairs (`size'
750 is really used for skipping to the next pair):
762 where `size' is the size of the associated structure in bytes, which
763 can be greater than the minimum of 20 bytes. `base_addr_low' is the
764 lower 32 bits of the starting address, and `base_addr_high' is the
766 is the lower 32 bits of the size of the memory region in bytes, and
767 `length_high' is the upper 32 bits, for a total of a 64-bit length.
768 `type' is the variety of address range represented, where a value of 1
775 If bit 7 in the `flags' is set, then the `drives_*' fields are
776 valid, and indicate the address of the physical address of the first
777 drive structure and the size of drive structures. `drives_addr' is the
778 address, and `drives_length' is the total size of drive structures.
796 The `size' field specifies the size of this structure. The size
797 varies, depending on the number of ports. Note that the size may not be
798 equal to (10 + 2 * the number of ports), because of an alignment.
800 The `drive_number' field contains the BIOS drive number. The
801 `drive_mode' field represents the access mode used by the boot loader.
802 Currently, the following modes are defined:
811 `drive_sectors', indicate the geometry of the drive detected by the
812 BIOS. `drive_cylinders' contains the number of the cylinders.
813 `drive_heads' contains the number of the heads. `drive_sectors'
814 contains the number of the sectors per track.
816 The `drive_ports' field contains the array of the I/O ports used for
817 the drive in the BIOS code. The array consists of zero or more unsigned
818 two-bytes integers, and is terminated with zero. Note that the array
819 may contain any number of I/O ports that are not related to the drive
822 If bit 8 in the `flags' is set, then the `config_table' field is
823 valid, and indicates the address of the ROM configuration table
824 returned by the "GET CONFIGURATION" BIOS call. If the BIOS call fails,
825 then the size of the table must be _zero_.
827 If bit 9 in the `flags' is set, the `boot_loader_name' field is
828 valid, and contains the physical address of the name of a boot loader
829 booting the kernel. The name is a normal C-style zero-terminated string.
831 If bit 10 in the `flags' is set, the `apm_table' field is valid, and
832 contains the physical address of an APM table defined as below:
847 `cseg_len', `cseg_16_len', `dseg_len' indicate the version number, the
848 protected mode 32-bit code segment, the offset of the entry point, the
849 protected mode 16-bit code segment, the protected mode 16-bit data
850 segment, the flags, the length of the protected mode 32-bit code
851 segment, the length of the protected mode 16-bit code segment, and the
852 length of the protected mode 16-bit data segment, respectively. Only
853 the field `offset' is 4 bytes, and the others are 2 bytes. See Advanced
858 If bit 11 in the `flags' is set, the graphics table is available.
859 This must only be done if the kernel has indicated in the `Multiboot
862 The fields `vbe_control_info' and `vbe_mode_info' contain the
863 physical addresses of VBE control information returned by the VBE
864 Function 00h and VBE mode information returned by the VBE Function 01h,
867 The field `vbe_mode' indicates current video mode in the format
871 `vbe_interface_len' contain the table of a protected mode interface
874 interface which is incompatible with the old one. If you want to use
875 the new protected mode interface, you will have to find the table
878 The fields for the graphics table are designed for VBE, but
888 *Caution:* The following items are not part of the specification
905 In reference to bit 0 of the `flags' parameter in the Multiboot
906 information structure, if the bootloader in question uses older BIOS
907 interfaces, or the newest ones are not available (see description about
912 In reference to bit 1 of the `flags' parameter in the Multiboot
917 many conditions. To encourage the use of general-purpose solutions to
921 In reference to bit 6 of the `flags' parameter in the Multiboot
922 information structure, it is important to note that the data structure
923 used there (starting with `BaseAddrLow') is the data returned by the
927 unmodified with any reasonable extensions of the BIOS interface,
928 passing along any extra data to be interpreted by the operating system
938 and neither require any special support in the drivers themselves. This
940 the I/O restriction technique.
942 The general rule is that the data comparison technique is the quick
943 and dirty solution. It works most of the time, but doesn't cover all the
947 potential to solve the problem under all conditions, plus allow access
948 of the remaining BIOS devices when not all of them have operating system
962 Before activating _any_ of the device drivers, gather enough data from
963 similar sectors on each of the disks such that each one can be uniquely
966 After activating the device drivers, compare data from the drives
967 using the operating system drivers. This should hopefully be sufficient
972 1. The data on some BIOS devices might be identical (so the part
973 reading the drives from the BIOS should have some mechanism to give
976 2. There might be extra drives not accessible from the BIOS which are
977 identical to some drive used by the BIOS (so it should be capable
987 mappings for the device drivers writing into PC RAM. Keep the original
988 copies for the "clean BIOS virtual machine" to be created later.
995 2. Set the I/O permission map for the I/O area claimed by the device
1000 4. Record which devices succeed, and those which try to access the
1004 For each device driver, given how many of the BIOS devices were
1006 to determine which devices on the controller these are.
1009 numbers, but they pretty much always count from the lowest logically
1010 numbered devices on the controller.
1018 In this distribution, the example Multiboot kernel `kernel' is
1019 included. The kernel just prints out the Multiboot information structure
1020 on the screen, so you can make use of the kernel to test a
1022 Multiboot kernel. The source files can be found under the directory
1023 `docs' in the GRUB distribution.
1027 in GAS (*note GNU assembler: (as.info)Top.), and contains the Multiboot
1028 information structure to comply with the specification. When a
1029 Multiboot-compliant boot loader loads and execute it, it initialize the
1030 stack pointer and `EFLAGS', and then call the function `cmain' defined
1031 in `kernel.c'. If `cmain' returns to the callee, then it shows a
1032 message to inform the user of the halt state and stops forever until
1033 you push the reset key. The file `kernel.c' contains the function
1034 `cmain', which checks if the magic number passed by the boot loader is
1035 valid and so on, and some functions to print messages on the screen.
1036 The file `multiboot.h' defines some macros, such as the magic number
1037 for the Multiboot header, the Multiboot header structure and the
1053 This is the source code in the file `multiboot.h':
1055 /* multiboot.h - the header for Multiboot */
1059 it under the terms of the GNU General Public License as published by
1060 the Free Software Foundation; either version 2 of the License, or
1063 This program is distributed in the hope that it will be useful,
1064 but WITHOUT ANY WARRANTY; without even the implied warranty of
1065 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1068 You should have received a copy of the GNU General Public License
1069 along with this program; if not, write to the Free Software
1074 /* The magic number for the Multiboot header. */
1077 /* The flags for the Multiboot header. */
1161 /* The memory map. Be careful that the offset 0 is base_addr_low
1181 In the file `boot.S':
1183 /* boot.S - bootstrap the kernel */
1187 it under the terms of the GNU General Public License as published by
1188 the Free Software Foundation; either version 2 of the License, or
1191 This program is distributed in the hope that it will be useful,
1192 but WITHOUT ANY WARRANTY; without even the implied warranty of
1193 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1196 You should have received a copy of the GNU General Public License
1197 along with this program; if not, write to the Free Software
1235 /* Initialize the stack pointer. */
1242 /* Push the pointer to the Multiboot information structure. */
1244 /* Push the magic value. */
1247 /* Now enter the C main function... */
1269 And, in the file `kernel.c':
1271 /* kernel.c - the C part of the kernel */
1275 it under the terms of the GNU General Public License as published by
1276 the Free Software Foundation; either version 2 of the License, or
1279 This program is distributed in the hope that it will be useful,
1280 but WITHOUT ANY WARRANTY; without even the implied warranty of
1281 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1284 You should have received a copy of the GNU General Public License
1285 along with this program; if not, write to the Free Software
1292 /* Check if the bit BIT in FLAGS is set. */
1306 /* Save the X position. */
1308 /* Save the Y position. */
1310 /* Point to the video memory. */
1320 /* Check if MAGIC is valid and print the Multiboot information structure
1327 /* Clear the screen. */
1337 /* Set MBI to the address of the Multiboot information structure. */
1340 /* Print out the flags. */
1352 /* Is the command line passed? */
1380 /* Is the symbol table of a.out valid? */
1392 /* Is the section header table of ELF valid? */
1425 /* Clear the screen and initialize VIDEO, XPOS and YPOS. */
1440 /* Convert the integer D to a string and save the string in BUF. If
1451 /* If %d is specified and D is minus, put `-' in the head. */
1486 /* Put the character C on the screen. */
1508 /* Format a string and print it on the screen, just like the libc
1564 is worth mentioning the OSKit
1566 supporting the specification.
1577 made, but the test release is available from:
1581 See the webpage `http://www.gnu.org/software/grub/grub.html', for
1595 * BIOS drive information, BIOS configuration table, the name of
1603 * The maintainer changes to the GNU GRUB maintainer team