From patchwork Thu Nov 24 20:40:00 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Kiper X-Patchwork-Id: 9446287 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id C8E54606DB for ; Thu, 24 Nov 2016 20:43:18 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B7E4127F8F for ; Thu, 24 Nov 2016 20:43:18 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id AC8BF27FB6; Thu, 24 Nov 2016 20:43:18 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 106B327F8F for ; Thu, 24 Nov 2016 20:43:17 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cA0p3-0001LI-JV; Thu, 24 Nov 2016 20:40:45 +0000 Received: from mail6.bemta3.messagelabs.com ([195.245.230.39]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cA0p2-0001Kk-QY for xen-devel@lists.xenproject.org; Thu, 24 Nov 2016 20:40:45 +0000 Received: from [85.158.137.68] by server-13.bemta-3.messagelabs.com id 59/71-23854-C4057385; Thu, 24 Nov 2016 20:40:44 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrHLMWRWlGSWpSXmKPExsXSO6nOVdcrwDz C4N4hVYvvWyYzOTB6HP5whSWAMYo1My8pvyKBNePvmhPsBY8bGCv+bZ3F3sDYmd3FyMUhJDCZ SeJ9w1VWCOc3o0Tz7UZ2CGcjo8S21e8ZIZyJjBLXW2YAZTg52AR0JC5+eQhmiwiYSTyb2QBWx CywiVFi5rZ5rCAJYYFgicv33oHZLAKqEree3gVr4BVwl2huuQBmSwgoSnQ/m8DWxcjBwSngIf HuoyRIWAio5NKko4wQJcYS7W8vsk1g5FvAyLCKUaM4tagstUjXyEAvqSgzPaMkNzEzR9fQwFg vN7W4ODE9NScxqVgvOT93EyMwXOoZGBh3MDaf8DvEKMnBpCTKu1nIPEKILyk/pTIjsTgjvqg0 J7X4EKMMB4eSBK+YP1BOsCg1PbUiLTMHGLgwaQkOHiUR3ku+QGne4oLE3OLMdIjUKUZFKXFeZ 5A+AZBERmkeXBssWi4xykoJ8zIyMDAI8RSkFuVmlqDKv2IU52BUEuY94Qc0hSczrwRu+iugxU xAiyW/GYMsLklESEk1MBY/6PRbYuRfvygi49acqaoeajJzX5249jT0l8ex6UF/yvkb4x53OfY ryZitv58426nHZ8Z+IW/WzW+72z25vLUkFjfJHzI+vt6habnp5PBchwNdHavYgi/ayXSf65/1 NP2kjP7HS4282l9aZaMDinXaI3dXPKyNvOP+/cz9+rQTO9QezbQTV2Ipzkg01GIuKk4EAEENq lKRAgAA X-Env-Sender: daniel.kiper@oracle.com X-Msg-Ref: server-13.tower-31.messagelabs.com!1480020040!72144636!1 X-Originating-IP: [141.146.126.69] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: VHJ1c3RlZCBJUDogMTQxLjE0Ni4xMjYuNjkgPT4gMjc3MjE4\n X-StarScan-Received: X-StarScan-Version: 9.0.16; banners=-,-,- X-VirusChecked: Checked Received: (qmail 25062 invoked from network); 24 Nov 2016 20:40:42 -0000 Received: from aserp1040.oracle.com (HELO aserp1040.oracle.com) (141.146.126.69) by server-13.tower-31.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 24 Nov 2016 20:40:42 -0000 Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id uAOKeWtj004514 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 24 Nov 2016 20:40:33 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id uAOKeWKL008124 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 24 Nov 2016 20:40:32 GMT Received: from abhmp0019.oracle.com (abhmp0019.oracle.com [141.146.116.25]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id uAOKeVhu020502; Thu, 24 Nov 2016 20:40:31 GMT Received: from olila.local.net-space.pl (/10.175.249.101) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 24 Nov 2016 12:40:31 -0800 From: Daniel Kiper To: grub-devel@gnu.org, xen-devel@lists.xenproject.org Date: Thu, 24 Nov 2016 21:40:00 +0100 Message-Id: <1480020010-18421-2-git-send-email-daniel.kiper@oracle.com> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1480020010-18421-1-git-send-email-daniel.kiper@oracle.com> References: <1480020010-18421-1-git-send-email-daniel.kiper@oracle.com> X-Source-IP: aserv0022.oracle.com [141.146.126.234] Cc: jgross@suse.com, eric.snowberg@oracle.com, arvidjaar@gmail.com, andrew.cooper3@citrix.com, seth.goldberg@oracle.com, phcoder@gmail.com Subject: [Xen-devel] [MULTIBOOT2 DOC PATCH v2 01/11] multiboot2: Rename Multiboot to Multiboot2 X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP Multiboot2 is proper name of the boot protocol. Multiboot is name of older boot protocol. So, rename Multiboot to Multiboot2 to not confuse the reader. Signed-off-by: Daniel Kiper --- doc/multiboot.texi | 112 ++++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/doc/multiboot.texi b/doc/multiboot.texi index 4b92918..d2b940f 100644 --- a/doc/multiboot.texi +++ b/doc/multiboot.texi @@ -2,7 +2,7 @@ @c %**start of header @setfilename multiboot.info @include version.texi -@settitle Multiboot Specification version @value{VERSION} +@settitle Multiboot2 Specification version @value{VERSION} @c Unify all our little indices for now. @syncodeindex fn cp @syncodeindex vr cp @@ -47,12 +47,12 @@ versions. @dircategory Kernel @direntry -* Multiboot Specification: (multiboot). Multiboot Specification. +* Multiboot2 Specification: (Multiboot2). Multiboot2 Specification. @end direntry @titlepage @sp 10 -@title The Multiboot Specification version @value{VERSION} +@title The Multiboot2 Specification version @value{VERSION} @author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn, Kunihiro Ishiguro, Vladimir 'phcoder' Serbinenko @page @vskip 0pt plus 1filll @@ -64,9 +64,9 @@ versions. @ifnottex @node Top -@top Multiboot Specification +@top Multiboot2 Specification -This file documents Multiboot Specification, the proposal for the boot +This file documents Multiboot2 Specification, the proposal for the boot sequence standard. This edition documents version @value{VERSION}. @insertcopying @@ -83,9 +83,9 @@ sequence standard. This edition documents version @value{VERSION}. @node Overview -@chapter Introduction to Multiboot Specification +@chapter Introduction to Multiboot2 Specification -This chapter describes some rough information on the Multiboot +This chapter describes some rough information on the Multiboot2 Specification. Note that this is not a part of the specification itself. @menu @@ -100,7 +100,7 @@ Specification. Note that this is not a part of the specification itself. @node Motivation -@section The background of Multiboot Specification +@section The background of Multiboot2 Specification Every operating system ever created tends to have its own boot loader. Installing a new operating system on a machine generally involves @@ -209,13 +209,13 @@ existence in order to load the OS image --- otherwise the boot loader effectively becomes operating system specific again. This specification adopts a compromise solution to this -problem. Multiboot-compliant OS images always contain a magic -@dfn{Multiboot header} (@pxref{OS image format}), which allows the boot +problem. Multiboot2-compliant OS images always contain a magic +@dfn{Multiboot2 header} (@pxref{OS image format}), which allows the boot loader to load the image without having to understand numerous a.out variants or other executable formats. This magic header does not need to be at the very beginning of the executable file, so kernel images can still conform to the local a.out format variant in addition to being -Multiboot-compliant. +Multiboot2-compliant. @node Boot modules @@ -246,7 +246,7 @@ because some operating systems will be unable to boot without them. @item must We use the term @dfn{must}, when any boot loader or OS image needs to follow a rule --- otherwise, the boot loader or OS image is @emph{not} -Multiboot-compliant. +Multiboot2-compliant. @item should We use the term @dfn{should}, when any boot loader or OS image is @@ -263,7 +263,7 @@ consist of several stages, but that is an implementation detail not relevant to this specification. Only the @emph{final} stage of the boot loader --- the stage that eventually transfers control to an operating system --- must follow the rules specified in this document in order -to be @dfn{Multiboot-compliant}; earlier boot loader stages may be +to be @dfn{Multiboot2-compliant}; earlier boot loader stages may be designed in whatever way is most convenient. @item OS image, kernel @@ -278,10 +278,10 @@ Other auxiliary files that a boot loader loads into memory along with an OS image, but does not interpret in any way other than passing their locations to the operating system when it is invoked. -@item Multiboot-compliant +@item Multiboot2-compliant A boot loader or an OS image which follows the rules defined as -@dfn{must} is Multiboot-compliant. When this specification specifies a -rule as @dfn{should} or @dfn{may}, a Multiboot-complaint boot loader/OS +@dfn{must} is Multiboot2-compliant. When this specification specifies a +rule as @dfn{should} or @dfn{may}, a Multiboot2-complaint boot loader/OS image doesn't need to follow the rule. @item u8 @@ -309,7 +309,7 @@ The type of unsigned data of the same size as target architecture virtual addres @node Specification -@chapter The exact definitions of Multiboot Specification +@chapter The exact definitions of Multiboot2 Specification There are three main aspects of a boot loader/OS image interface: @@ -342,17 +342,17 @@ linked at a non-default load address to avoid loading on top of the @sc{pc}'s I/O region or other reserved areas, and of course it should not use shared libraries or other fancy features. -An OS image must contain an additional header called @dfn{Multiboot +An OS image must contain an additional header called @dfn{Multiboot2 header}, besides the headers of the format used by the OS image. The -Multiboot header must be contained completely within the first 32768 +Multiboot2 header must be contained completely within the first 32768 bytes of the OS image, and must be 64-bit aligned. In general, it should come @emph{as early as possible}, and may be embedded in the beginning of the text segment after the @emph{real} executable header. @menu -* Header layout:: The layout of Multiboot header -* Header magic fields:: The magic fields of Multiboot header +* Header layout:: The layout of Multiboot2 header +* Header magic fields:: The magic fields of Multiboot2 header * Header tags:: * Information request header tag:: * Address header tag:: @@ -363,9 +363,9 @@ executable header. @node Header layout -@subsection The layout of Multiboot header +@subsection The layout of Multiboot2 header -The layout of the Multiboot header must be as follows: +The layout of the Multiboot2 header must be as follows: @multitable @columnfractions .1 .1 .2 .5 @item Offset @tab Type @tab Field Name @tab Note @@ -382,7 +382,7 @@ On bi-endian platforms native-endianness means the endiannes OS image starts in. @node Header magic fields -@subsection The magic fields of Multiboot header +@subsection The magic fields of Multiboot2 header @table @samp @item magic @@ -397,7 +397,7 @@ recieve the same ID. @samp{0} means 32-bit (protected) mode of i386. @samp{4} means 32-bit MIPS. @item header_length -The field @samp{header_length} specifies the Length of multiboot header +The field @samp{header_length} specifies the Length of Multiboot2 header in bytes including magic fields. @@ -430,7 +430,7 @@ lacks relevant support. Tags are terminated by a tag of type @samp{0} and size @samp{8}. @node Information request header tag -@subsection Multiboot information request +@subsection Multiboot2 information request @example @group @@ -455,7 +455,7 @@ actually be present. E.g. on a videoless system even if you requested tag @node Address header tag -@subsection The address tag of Multiboot header +@subsection The address tag of Multiboot2 header @example @group @@ -476,7 +476,7 @@ The meaning of each is as follows: @table @code @item header_addr -Contains the address corresponding to the beginning of the Multiboot +Contains the address corresponding to the beginning of the Multiboot2 header --- the physical memory location at which the magic value is supposed to be loaded. This field serves to @dfn{synchronize} the mapping between OS image offsets and physical memory addresses. @@ -506,7 +506,7 @@ assumes that no bss segment is present. @end table -@subsection The entry address tag of Multiboot header +@subsection The entry address tag of Multiboot2 header @example @group @@ -548,7 +548,7 @@ at least one of supported consoles must be present and information about it must If bit @samp{1} of @samp{console_flags} is set it indicates that the OS image has EGA text support. -@subsection The framebuffer tag of Multiboot header +@subsection The framebuffer tag of Multiboot2 header @example @group @@ -630,11 +630,11 @@ must have the following state: @item R4 (also known as A0) Must contain the magic value @samp{0x36d76289}; the presence of this value indicates to the operating system that it was loaded by a -Multiboot-compliant boot loader (e.g. as opposed to another type of +Multiboot2-compliant boot loader (e.g. as opposed to another type of boot loader that the operating system can also be loaded from). @item R5 (also known as A1) -Must contain the 32-bit physical address of the Multiboot +Must contain the 32-bit physical address of the Multiboot2 information structure provided by the boot loader (@pxref{Boot information format}). @end table @@ -657,11 +657,11 @@ must have the following state: @item EAX Must contain the magic value @samp{0x36d76289}; the presence of this value indicates to the operating system that it was loaded by a -Multiboot-compliant boot loader (e.g. as opposed to another type of +Multiboot2-compliant boot loader (e.g. as opposed to another type of boot loader that the operating system can also be loaded from). @item EBX -Must contain the 32-bit physical address of the Multiboot +Must contain the 32-bit physical address of the Multiboot2 information structure provided by the boot loader (@pxref{Boot information format}). @@ -714,13 +714,13 @@ On EFI system boot services must be terminated. @subsection Boot information format Upon entry to the operating system, the @code{EBX} register contains the -physical address of a @dfn{Multiboot information} data structure, +physical address of a @dfn{Multiboot2 information} data structure, through which the boot loader communicates vital information to the operating system. The operating system can use or ignore any parts of the structure as it chooses; all information passed by the boot loader is advisory only. -The Multiboot information structure and its related substructures may be +The Multiboot2 information structure and its related substructures may be placed anywhere in memory by the boot loader (with the exception of the memory reserved for the kernel and boot modules, of course). It is the operating system's responsibility to avoid overwriting this memory until @@ -1190,14 +1190,14 @@ loader writers. @node Notes on PC @section Notes on PC -In reference to bit 0 of the @samp{flags} parameter in the Multiboot +In reference to bit 0 of the @samp{flags} parameter in the Multiboot2 information structure, if the bootloader in question uses older @sc{bios} interfaces, or the newest ones are not available (see description about bit 6), then a maximum of either 15 or 63 megabytes of memory may be reported. It is @emph{highly} recommended that boot loaders perform a thorough memory probe. -In reference to bit 1 of the @samp{flags} parameter in the Multiboot +In reference to bit 1 of the @samp{flags} parameter in the Multiboot2 information structure, it is recognized that determination of which @sc{bios} drive maps to which device driver in an operating system is non-trivial, at best. Many kludges have been made to various operating @@ -1206,7 +1206,7 @@ many conditions. To encourage the use of general-purpose solutions to this problem, there are 2 @sc{bios} device mapping techniques (@pxref{BIOS device mapping techniques}). -In reference to bit 6 of the @samp{flags} parameter in the Multiboot +In reference to bit 6 of the @samp{flags} parameter in the Multiboot2 information structure, it is important to note that the data structure used there (starting with @samp{BaseAddrLow}) is the data returned by the INT 15h, AX=E820h --- Query System Address Map call. See @xref{Query @@ -1306,18 +1306,18 @@ logically numbered devices on the controller. @node Example OS code @section Example OS code -In this distribution, the example Multiboot kernel @file{kernel} is -included. The kernel just prints out the Multiboot information structure +In this distribution, the example Multiboot2 kernel @file{kernel} is +included. The kernel just prints out the Multiboot2 information structure on the screen, so you can make use of the kernel to test a -Multiboot-compliant boot loader and for reference to how to implement a -Multiboot kernel. The source files can be found under the directory -@file{doc} in the Multiboot source distribution. +Multiboot2-compliant boot loader and for reference to how to implement a +Multiboot2 kernel. The source files can be found under the directory +@file{doc} in the Multiboot2 source distribution. The kernel @file{kernel} consists of only three files: @file{boot.S}, @file{kernel.c} and @file{multiboot2.h}. The assembly source @file{boot.S} is written in GAS (@pxref{Top, , GNU assembler, as.info, -The GNU assembler}), and contains the Multiboot information structure to -comply with the specification. When a Multiboot-compliant boot loader +The GNU assembler}), and contains the Multiboot2 information structure to +comply with the specification. When a Multiboot2-compliant boot loader loads and execute it, it initialize the stack pointer and @code{EFLAGS}, and then call the function @code{cmain} defined in @file{kernel.c}. If @code{cmain} returns to the callee, then it shows a message to inform @@ -1326,14 +1326,14 @@ key. The file @file{kernel.c} contains the function @code{cmain}, which checks if the magic number passed by the boot loader is valid and so on, and some functions to print messages on the screen. The file @file{multiboot2.h} defines some macros, such as the magic number for the -Multiboot header, the Multiboot header structure and the Multiboot +Multiboot2 header, the Multiboot2 header structure and the Multiboot2 information structure. @menu * multiboot2.h:: * boot.S:: * kernel.c:: -* Other Multiboot kernels:: +* Other Multiboot2 kernels:: @end menu @@ -1367,10 +1367,10 @@ And, in the file @file{kernel.c}: @end example -@node Other Multiboot kernels -@subsection Other Multiboot kernels +@node Other Multiboot2 kernels +@subsection Other Multiboot2 kernels -Other useful information should be available in Multiboot kernels, such +Other useful information should be available in Multiboot2 kernels, such as GNU Mach and Fiasco @url{http://os.inf.tu-dresden.de/fiasco/}. And, it is worth mentioning the OSKit @url{http://www.cs.utah.edu/projects/flux/oskit/}, which provides a @@ -1381,7 +1381,7 @@ library supporting the specification. @section Example boot loader code The GNU GRUB (@pxref{Top, , GRUB, grub.info, The GRUB manual}) project -is a Multiboot-compliant boot loader, supporting all required and +is a Multiboot2-compliant boot loader, supporting all required and many optional features present in this specification. A public release has not been made, but the test release is available from: @@ -1398,14 +1398,14 @@ more information. @item 0.7 @itemize @bullet @item -@dfn{Multiboot Standard} is renamed to @dfn{Multiboot Specification}. +@dfn{Multiboot2 Standard} is renamed to @dfn{Multiboot2 Specification}. @item -Graphics fields are added to Multiboot header. +Graphics fields are added to Multiboot2 header. @item BIOS drive information, BIOS configuration table, the name of a boot -loader, APM information, and graphics information are added to Multiboot +loader, APM information, and graphics information are added to Multiboot2 information. @item @@ -1419,7 +1419,7 @@ The maintainer changes to the GNU GRUB maintainer team @email{bug-grub@@gnu.org}, from Bryan Ford and Erich Stefan Boleyn. @item -The byte order of the @samp{boot_device} in Multiboot information is +The byte order of the @samp{boot_device} in Multiboot2 information is reversed. This was a mistake. @item