Re: [MULTIBOOT2 DOC PATCH v2 05/11] multiboot2: Add description of support for EFI boot services

[Toomas Soome]

There is still the same confusion as with entry address tag 7; the diagram has 
u_virt, yet the text does claim it is physical address. Sure, it is assumed the 
identity mapping, but still those names are creating confusion.

Moreover, the EFI32 and EFI64 have different address sizes (32 versus 64 bit), 
yet there is the same type: u_virt - so it hints the upper part of the 64bit 
address is ignored, but its not really clear from the text…

rgds,
toomas


> On 24. nov 2016, at 22:40, Daniel Kiper <address@hidden> wrote:
> 
> Signed-off-by: Daniel Kiper <address@hidden>
> ---
> v2 - suggestions/fixes:
>   - clarify physical address meaning for EFI amd64
>     mode with boot services enabled
>     (suggested by Andrew Cooper).
> ---
> doc/multiboot.texi |  115 +++++++++++++++++++++++++++++++++++++++++++++++++++-
> doc/multiboot2.h   |    2 +
> 2 files changed, 115 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/multiboot.texi b/doc/multiboot.texi
> index f0f167e..cc1edab 100644
> --- a/doc/multiboot.texi
> +++ b/doc/multiboot.texi
> @@ -534,6 +534,66 @@ The physical address to which the boot loader should 
> jump in order to
> start running the operating system.
> @end table
> 
> address@hidden EFI i386 entry address tag of Multiboot2 header
> +
> address@hidden
> address@hidden
> +        +-------------------+
> +u16     | type = 8          |
> +u16     | flags             |
> +u32     | size              |
> +u_virt  | entry_addr        |
> +        +-------------------+
> address@hidden group
> address@hidden example
> +
> +All of the address fields in this tag are physical addresses.
> +The meaning of each is as follows:
> +
> address@hidden @code
> +
> address@hidden entry_addr
> +The physical address to which the boot loader should jump in order to
> +start running EFI i386 compatible operating system code.
> address@hidden 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.
> +
> address@hidden EFI amd64 entry address tag of Multiboot2 header
> +
> address@hidden
> address@hidden
> +        +-------------------+
> +u16     | type = 9          |
> +u16     | flags             |
> +u32     | size              |
> +u_virt  | entry_addr        |
> +        +-------------------+
> address@hidden group
> address@hidden 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:
> +
> address@hidden @code
> +
> address@hidden entry_addr
> +The physical address to which the boot loader should jump in order to
> +start running EFI amd64 compatible operating system code.
> address@hidden 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
> 
> @@ -714,12 +774,63 @@ The OS image must leave interrupts disabled until it 
> sets up its own
> 
> On EFI system boot services must be terminated.
> 
> address@hidden 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:
> +
> address@hidden @samp
> address@hidden 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
> +boot loader that the operating system can also be loaded from).
> +
> address@hidden EBX
> +Must contain the 32-bit physical address of the Multiboot2
> +information structure provided by the boot loader (@pxref{Boot
> +information format}).
> address@hidden 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.
> +
> address@hidden 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:
> +
> address@hidden @samp
> address@hidden RAX
> +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
> +boot loader that the operating system can also be loaded from).
> +
> address@hidden RBX
> +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}).
> address@hidden 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.
> +
> @node Boot information format
> @section Boot information
> @subsection Boot information format
> 
> -Upon entry to the operating system, the @code{EBX} register contains the
> -physical address of a @dfn{Multiboot2 information} data structure,
> +Upon entry to the operating system, the @code{R5/EBX/RBX} register contains
> +the 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
> 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
> -- 
> 1.7.10.4
> 
> 
> _______________________________________________
> Grub-devel mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/grub-devel