[MULTIBOOT2,DOC,v3,07/13] multiboot2: Add description of support for EFI boot services
diff mbox

Message ID 1481064781-16949-8-git-send-email-daniel.kiper@oracle.com
State New, archived
Headers show

Commit Message

Daniel Kiper Dec. 6, 2016, 10:52 p.m. UTC
Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
---
v3 - suggestions/fixes:
   - replace u_virt with u32
     (suggested by Andrei Borzenkov and Toomas Soome),
   - change RAX/RBX to EAX/EBX in "EFI amd64 machine state with boot
     services enabled" section,
   - describe the kernel, the modules, etc. load addresses limitation
     in "EFI amd64 machine state with boot services enabled" section,
   - replace Multiboot-compliant with Multiboot2-compliant.

v2 - suggestions/fixes:
   - clarify physical address meaning for EFI amd64
     mode with boot services enabled
     (suggested by Andrew Cooper).
---
 doc/multiboot.texi |  124 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/multiboot2.h   |    2 +
 2 files changed, 126 insertions(+)

Comments

Konrad Rzeszutek Wilk Dec. 7, 2016, 2:33 p.m. UTC | #1
.snip..
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -528,6 +528,66 @@ The physical address to which the boot loader should jump in order to
>  start running the operating system.
>  @end table
>  
> +@subsection EFI i386 entry address tag of Multiboot2 header
> +
> +@example
> +@group
> +        +-------------------+
> +u16     | type = 8          |
> +u16     | flags             |


Would it make sense to describe what 'flags' should contain? Or at least
if there is nothing yet there mention that the value is ignored and
should be zero?
Daniel Kiper Dec. 7, 2016, 6:21 p.m. UTC | #2
On Wed, Dec 07, 2016 at 09:33:55AM -0500, Konrad Rzeszutek Wilk wrote:
> ..snip..
> > --- a/doc/multiboot.texi
> > +++ b/doc/multiboot.texi
> > @@ -528,6 +528,66 @@ The physical address to which the boot loader should jump in order to
> >  start running the operating system.
> >  @end table
> >
> > +@subsection EFI i386 entry address tag of Multiboot2 header
> > +
> > +@example
> > +@group
> > +        +-------------------+
> > +u16     | type = 8          |
> > +u16     | flags             |
>
>
> Would it make sense to describe what 'flags' should contain? Or at least
> if there is nothing yet there mention that the value is ignored and
> should be zero?

'flags' is generic field and it is described earlier in the document.

Daniel

Patch
diff mbox

diff --git a/doc/multiboot.texi b/doc/multiboot.texi
index 9af756a..9f13e74 100644
--- a/doc/multiboot.texi
+++ b/doc/multiboot.texi
@@ -528,6 +528,66 @@  The physical address to which the boot loader should jump in order to
 start running the operating system.
 @end table
 
+@subsection EFI i386 entry address tag of Multiboot2 header
+
+@example
+@group
+        +-------------------+
+u16     | type = 8          |
+u16     | flags             |
+u32     | size              |
+u32     | entry_addr        |
+        +-------------------+
+@end group
+@end example
+
+All of the address fields in this tag are physical addresses.
+The meaning of each is as follows:
+
+@table @code
+
+@item entry_addr
+The physical address to which the boot loader should jump in order to
+start running EFI i386 compatible operating system code.
+@end table
+
+This tag is taken into account only on EFI i386 platforms
+when Multiboot2 image header contains EFI boot services tag.
+Then entry point specified in ELF header and the entry address
+tag of Multiboot2 header are ignored.
+
+@subsection EFI amd64 entry address tag of Multiboot2 header
+
+@example
+@group
+        +-------------------+
+u16     | type = 9          |
+u16     | flags             |
+u32     | size              |
+u32     | entry_addr        |
+        +-------------------+
+@end group
+@end example
+
+All of the address fields in this tag are physical addresses (paging
+mode is enabled and any memory space defined by the UEFI memory map
+is identity mapped, hence, virtual address equals physical address;
+Unified Extensible Firmware Interface Specification, Version 2.6,
+section 2.3.4, x64 Platforms, boot services). The meaning of each
+is as follows:
+
+@table @code
+
+@item entry_addr
+The physical address to which the boot loader should jump in order to
+start running EFI amd64 compatible operating system code.
+@end table
+
+This tag is taken into account only on EFI amd64 platforms
+when Multiboot2 image header contains EFI boot services tag.
+Then entry point specified in ELF header and the entry address
+tag of Multiboot2 header are ignored.
+
 @node Console header tags
 @subsection Flags tag
 
@@ -708,6 +768,70 @@  The OS image must leave interrupts disabled until it sets up its own
 
 On EFI system boot services must be terminated.
 
+@section EFI i386 machine state with boot services enabled
+
+When the boot loader invokes the 32-bit operating system on EFI i386
+platform and EFI boot services tag together with EFI i386 entry address
+tag are present in the image Multiboot2 header, the machine must have the
+following state:
+
+@table @samp
+@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
+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 Multiboot2
+information structure provided by the boot loader (@pxref{Boot
+information format}).
+@end table
+
+All other processor registers, flag bits and state are set accordingly
+to Unified Extensible Firmware Interface Specification, Version 2.6,
+section 2.3.2, IA-32 Platforms, boot services.
+
+@section EFI amd64 machine state with boot services enabled
+
+When the boot loader invokes the 64-bit operating system on EFI amd64
+platform and EFI boot services tag together with EFI amd64 entry address
+tag are present in the image Multiboot2 header, the machine must have the
+following state:
+
+@table @samp
+@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
+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 64-bit physical address (paging mode is enabled and any
+memory space defined by the UEFI memory map is identity mapped, hence,
+virtual address equals physical address; Unified Extensible Firmware
+Interface Specification, Version 2.6, section 2.3.4, x64 Platforms, boot
+services) of the Multiboot2 information structure provided by the boot
+loader (@pxref{Boot information format}).
+@end table
+
+All other processor registers, flag bits and state are set accordingly
+to Unified Extensible Firmware Interface Specification, Version 2.6,
+section 2.3.4, x64 Platforms, boot services.
+
+The bootloader must not load any part of the kernel, the modules, the Multiboot2
+information structure, etc. higher than 4 GiB - 1. This requirement is put in
+force because most of currently specified tags supports 32-bit addresses only.
+Additionally, some kernels, even if they run on EFI 64-bit platform, still
+execute some parts of its initialization code in 32-bit mode.
+
+Note: If at some point there is a need for full 64-bit mode support in Multiboot2
+protocol then it should be designed very carefully. Especially it should be taken
+into account that 32-bit and 64-bit mode code should coexist in an image without
+any issue. The image should have a chance to inform the bootloader that it supports
+full 64-bit mode. If it is the case then the bootloader should provide 64-bit tags
+if it is desired and possible. Otherwise 32-bit tags should be used.
+
 @node Boot information format
 @section Boot information
 @subsection Boot information format
diff --git a/doc/multiboot2.h b/doc/multiboot2.h
index 78337f5..240400d 100644
--- a/doc/multiboot2.h
+++ b/doc/multiboot2.h
@@ -69,6 +69,8 @@ 
 #define MULTIBOOT_HEADER_TAG_FRAMEBUFFER  5
 #define MULTIBOOT_HEADER_TAG_MODULE_ALIGN  6
 #define MULTIBOOT_HEADER_TAG_EFI_BS        7
+#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI32  8
+#define MULTIBOOT_HEADER_TAG_ENTRY_ADDRESS_EFI64  9
 
 #define MULTIBOOT_ARCHITECTURE_I386  0
 #define MULTIBOOT_ARCHITECTURE_MIPS32  4