From 9ca8f72a9297f2052d806bd1111e176533aa69bd Mon Sep 17 00:00:00 2001 From: Matt Fleming Date: Thu, 19 Jul 2012 10:23:48 +0100 Subject: x86, efi: Handover Protocol As things currently stand, traditional EFI boot loaders and the EFI boot stub are carrying essentially the same initialisation code required to setup an EFI machine for booting a kernel. There's really no need to have this code in two places and the hope is that, with this new protocol, initialisation and booting of the kernel can be left solely to the kernel's EFI boot stub. The responsibilities of the boot loader then become, o Loading the kernel image from boot media File system code still needs to be carried by boot loaders for the scenario where the kernel and initrd files reside on a file system that the EFI firmware doesn't natively understand, such as ext4, etc. o Providing a user interface Boot loaders still need to display any menus/interfaces, for example to allow the user to select from a list of kernels. Bump the boot protocol number because we added the 'handover_offset' field to indicate the location of the handover protocol entry point. Cc: H. Peter Anvin Cc: Peter Jones Cc: Ingo Molnar Signed-off-by: Matt Fleming Acked-and-Tested-by: Matthew Garrett Link: http://lkml.kernel.org/r/1342689828-16815-1-git-send-email-matt@console-pimps.org Signed-off-by: H. Peter Anvin --- Documentation/x86/boot.txt | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 7c3a8801b7c..c6539a4278b 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -54,6 +54,9 @@ Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment beyond the kernel_alignment added, new init_size and pref_address fields. Added extended boot loader IDs. +Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover + protocol entry point. + **** MEMORY LAYOUT The traditional memory map for the kernel loader, used for Image or @@ -189,6 +192,7 @@ Offset Proto Name Meaning of struct setup_data 0258/8 2.10+ pref_address Preferred loading address 0260/4 2.10+ init_size Linear memory required during initialization +0264/4 2.11+ handover_offset Offset of handover entry point (1) For backwards compatibility, if the setup_sects field contains 0, the real value is 4. @@ -690,6 +694,16 @@ Offset/size: 0x260/4 else runtime_start = pref_address +Field name: handover_offset +Type: read +Offset/size: 0x264/4 + + This field is the offset from the beginning of the kernel image to + the EFI handover protocol entry point. Boot loaders using the EFI + handover protocol to boot the kernel should jump to this offset. + + See EFI HANDOVER PROTOCOL below for more details. + **** THE IMAGE CHECKSUM @@ -1010,3 +1024,30 @@ segment; __BOOS_CS must have execute/read permission, and __BOOT_DS must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %esi must hold the base address of the struct boot_params; %ebp, %edi and %ebx must be zero. + +**** EFI HANDOVER PROTOCOL + +This protocol allows boot loaders to defer initialisation to the EFI +boot stub. The boot loader is required to load the kernel/initrd(s) +from the boot media and jump to the EFI handover protocol entry point +which is hdr->handover_offset bytes from the beginning of +startup_{32,64}. + +The function prototype for the handover entry point looks like this, + + efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp) + +'handle' is the EFI image handle passed to the boot loader by the EFI +firmware, 'table' is the EFI system table - these are the first two +arguments of the "handoff state" as described in section 2.3 of the +UEFI specification. 'bp' is the boot loader-allocated boot params. + +The boot loader *must* fill out the following fields in bp, + + o hdr.code32_start + o hdr.cmd_line_ptr + o hdr.cmdline_size + o hdr.ramdisk_image (if applicable) + o hdr.ramdisk_size (if applicable) + +All other fields should be zero. -- cgit v1.2.3 From c5e5c42a68be66cb87573e5c2fcce6f1b5d82bd5 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Mon, 23 Jul 2012 16:16:17 -0700 Subject: x86, doc: Assign a bootloader ID for "Minimal Linux Bootloader" Assign a bootloader ID for Sebastian Plotz' "Minimal Linux Bootloader" (http://sebastian-plotz.blogspot.de). Sebastian has agreed to make this the pilot for the use of extended boot loader IDs, so this is assigned version ID 0x11 (avoid assigning 0x10 for now to catch bugs with people putting E in the primary ID but leaving the extended ID as zero.) Signed-off-by: H. Peter Anvin Cc: Sebastian Plotz Link: http://lkml.kernel.org/n/tip-nq318h0okuaem8x9dpv9854k@git.kernel.org --- Documentation/x86/boot.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 7c3a8801b7c..473b32fd544 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -363,7 +363,8 @@ Protocol: 2.00+ ext_loader_type <- 0x05 ext_loader_ver <- 0x23 - Assigned boot loader ids: + Assigned boot loader ids (hexadecimal): + 0 LILO (0x00 reserved for pre-2.00 bootloader) 1 Loadlin 2 bootsect-loader (0x20, all other values reserved) @@ -378,6 +379,8 @@ Protocol: 2.00+ C Arcturus Networks uCbootloader E Extended (see ext_loader_type) F Special (0xFF = undefined) + 10 Reserved + 11 Minimal Linux Bootloader Please contact if you need a bootloader ID value assigned. -- cgit v1.2.3 From c6039f4a00901259517b7c027007697105209968 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 25 Oct 2012 20:17:02 -0700 Subject: x86/boot/doc: Fix grammar and typo in boot.txt Fixes some minor issues in the x86 boot documentation. Signed-off-by: Kees Cook Cc: Rob Landley Link: http://lkml.kernel.org/r/20121026031702.GA23828@www.outflux.net Signed-off-by: Ingo Molnar --- Documentation/x86/boot.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 9efceff51bf..f15cb74c4f7 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -1013,7 +1013,7 @@ boot_params as that of 16-bit boot protocol, the boot loader should also fill the additional fields of the struct boot_params as that described in zero-page.txt. -After setupping the struct boot_params, the boot loader can load the +After setting up the struct boot_params, the boot loader can load the 32/64-bit kernel in the same way as that of 16-bit boot protocol. In 32-bit boot protocol, the kernel is started by jumping to the @@ -1023,7 +1023,7 @@ In 32-bit boot protocol, the kernel is started by jumping to the At entry, the CPU must be in 32-bit protected mode with paging disabled; a GDT must be loaded with the descriptors for selectors __BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat -segment; __BOOS_CS must have execute/read permission, and __BOOT_DS +segment; __BOOT_CS must have execute/read permission, and __BOOT_DS must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %esi must hold the base address of the struct boot_params; %ebp, %edi and %ebx must be zero. -- cgit v1.2.3 From 4bfe24ac1d9d9f06b30b2909f53ea462c72cfe1d Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Wed, 12 Dec 2012 20:24:12 -0800 Subject: x86, doc: Add a formal bootloader ID for kexec-tools Add bootloader id D for kexec-tools (it is kexec-tools, not the kexec system call, that builds the data structures, therefore it is kexec-tools which is the "bootloader" for this purpose.) Signed-off-by: H. Peter Anvin Cc: Eric W. Biederman Cc: Yinghai Lu Link: http://lkml.kernel.org/r/50C95832.5030306@zytor.com --- Documentation/x86/boot.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 9efceff51bf..c25a53e69f1 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -381,6 +381,7 @@ Protocol: 2.00+ A Gujin B Qemu C Arcturus Networks uCbootloader + D kexec-tools E Extended (see ext_loader_type) F Special (0xFF = undefined) 10 Reserved -- cgit v1.2.3 From cd34ab8b16ffaa9753d85adb4fb6cd98e7e1d22a Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Wed, 12 Dec 2012 20:28:39 -0800 Subject: x86, doc: Document that bootloader ID 4 is used also by iPXE Etherboot -> gPXE -> iPXE... Signed-off-by: H. Peter Anvin Cc: Michael Brown --- Documentation/x86/boot.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index c25a53e69f1..9a89e01d9bc 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -373,7 +373,7 @@ Protocol: 2.00+ 1 Loadlin 2 bootsect-loader (0x20, all other values reserved) 3 Syslinux - 4 Etherboot/gPXE + 4 Etherboot/gPXE/iPXE 5 ELILO 7 GRUB 8 U-Boot -- cgit v1.2.3 From 09c205afde70c15f20ca76ba0a57409dad175fd0 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Sun, 27 Jan 2013 10:43:28 -0800 Subject: x86, boot: Define the 2.12 bzImage boot protocol Define the 2.12 bzImage boot protocol: add xloadflags and additional fields to allow the command line, initramfs and struct boot_params to live above the 4 GiB mark. The xloadflags now communicates if this is a 64-bit kernel with the legacy 64-bit entry point and which of the EFI handover entry points are supported. Avoid adding new read flags to loadflags because of claimed bootloaders testing the whole byte for == 1 to determine bzImageness at least until the issue can be researched further. This is based on patches by Yinghai Lu and David Woodhouse. Originally-by: Yinghai Lu Originally-by: David Woodhouse Acked-by: Yinghai Lu Acked-by: David Woodhouse Acked-by: Matt Fleming Signed-off-by: H. Peter Anvin Link: http://lkml.kernel.org/r/1359058816-7615-26-git-send-email-yinghai@kernel.org Cc: Rob Landley Cc: Gokul Caushik Cc: Josh Triplett Cc: Joe Millenbach --- Documentation/x86/boot.txt | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 406d82d5d2b..3edb4c2887a 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -57,6 +57,10 @@ Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover protocol entry point. +Protocol 2.12: (Kernel 3.9) Added the xloadflags field and extension fields + to struct boot_params for for loading bzImage and ramdisk + above 4G in 64bit. + **** MEMORY LAYOUT The traditional memory map for the kernel loader, used for Image or @@ -182,7 +186,7 @@ Offset Proto Name Meaning 0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel 0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not 0235/1 2.10+ min_alignment Minimum alignment, as a power of two -0236/2 N/A pad3 Unused +0236/2 2.12+ xloadflags Boot protocol option flags 0238/4 2.06+ cmdline_size Maximum size of the kernel command line 023C/4 2.07+ hardware_subarch Hardware subarchitecture 0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data @@ -582,6 +586,27 @@ Protocol: 2.10+ misaligned kernel. Therefore, a loader should typically try each power-of-two alignment from kernel_alignment down to this alignment. +Field name: xloadflags +Type: read +Offset/size: 0x236/2 +Protocol: 2.12+ + + This field is a bitmask. + + Bit 0 (read): XLF_KERNEL_64 + - If 1, this kernel has the legacy 64-bit entry point at 0x200. + + Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G + - If 1, kernel/boot_params/cmdline/ramdisk can be above 4G. + + Bit 2 (read): XLF_EFI_HANDOVER_32 + - If 1, the kernel supports the 32-bit EFI handoff entry point + given at handover_offset. + + Bit 3 (read): XLF_EFI_HANDOVER_64 + - If 1, the kernel supports the 64-bit EFI handoff entry point + given at handover_offset + 0x200. + Field name: cmdline_size Type: read Offset/size: 0x238/4 -- cgit v1.2.3 From 972f7c832229781f09f03284cde484ccdb44d3ee Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Thu, 31 Jan 2013 20:23:49 -0800 Subject: x86, doc: Boot protocol 2.12 is in 3.8 The boot protocol 2.12 changes were pulled for 3.8, so update the documentation accordingly. Signed-off-by: H. Peter Anvin --- Documentation/x86/boot.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 3edb4c2887a..e540fd67f76 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -57,7 +57,7 @@ Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover protocol entry point. -Protocol 2.12: (Kernel 3.9) Added the xloadflags field and extension fields +Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields to struct boot_params for for loading bzImage and ramdisk above 4G in 64bit. -- cgit v1.2.3 From 686966d881bd49bd6349b47c59dfc4bfc7b5e3b6 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Fri, 8 Feb 2013 09:19:33 -0800 Subject: x86, doc: Add a bootloader ID for OVMF OVMF (an implementation of UEFI based on TianoCore used in virtual environments) now has the ability to boot Linux natively; this is used for "qemu -kernel" and similar things in a UEFI environment. Accordingly, assign it a bootloader ID. Signed-off-by: H. Peter Anvin Cc: David Woodhouse --- Documentation/x86/boot.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/x86/boot.txt') diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index e540fd67f76..b443f1de0e5 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -390,6 +390,7 @@ Protocol: 2.00+ F Special (0xFF = undefined) 10 Reserved 11 Minimal Linux Bootloader + 12 OVMF UEFI virtualization stack Please contact if you need a bootloader ID value assigned. -- cgit v1.2.3