Skip to contentSkip to conversation

Documentation: Fix x86_64 UEFI outdated references to elilo

PATCH In review Nir Lichtman 3 participants 4 messages Jan 8, 2025 – Jan 16, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 Documentation: Fix x86_64 UEFI outdated references to elilo

Problem: The x86_64 UEFI doc references Elilo which is an unmaintained/orphaned bootloader project. Also, on x86_64 a bootloader is technically not actually required since there is support for the Linux EFI stub.

Solution: Remove the references to Elilo from the doc and refer to the EFI stub doc page, update steps accordingly, and add more details about creation of the EFI partition to improve clarity.

---

v2: Fix list not rendered properly and minor wording fixes (thanks for the CR Bagas) Also fix to use shorter lines

 Documentation/arch/x86/x86_64/uefi.rst | 36 +++++++++++++++++++-------
 1 file changed, 26 insertions(+), 10 deletions(-)
Documentation/arch/x86/x86_64/uefi.rst +26 -10
index fbc30c9a071d..3949d83a9915 100644
@@ -12,14 +12,19 @@ with EFI firmware and specifications are listed below.
 
 1. UEFI specification:  http://www.uefi.org
 
-2. Booting Linux kernel on UEFI x86_64 platform requires bootloader
-   support. Elilo with x86_64 support can be used.
+2. Booting Linux kernel on UEFI x86_64 platform can either be
+   done using the <Documentation/admin-guide/efi-stub.rst> or using a separate bootloader.
 
 3. x86_64 platform with EFI/UEFI firmware.
 
 Mechanics
 ---------
 
+Refer to <Documentation/admin-guide/efi-stub.rst> to learn how to use the EFI stub.
+
+Below are general EFI setup guidelines on the x86_64 platform,
+regardless of whether you use the EFI stub or a separate bootloader.
+
 - Build the kernel with the following configuration::
 
 	CONFIG_FB_EFI=y
@@ -31,16 +36,27 @@ Mechanics
 	CONFIG_EFI=y
 	CONFIG_EFIVAR_FS=y or m		# optional
 
-- Create a VFAT partition on the disk
-- Copy the following to the VFAT partition:
+- Create a VFAT partition on the disk with the EFI System flag
+    You can do this with fdisk with the following commands:
+
+        1. g - initialize a GPT partition table
+        2. n - create a new partition
+        3. t - change the partition type to "EFI System" (number 1)
+        4. w - write and save the changes
+
+    Afterwards, initialize the VFAT filesystem by running mkfs::
+
+        mkfs.fat /dev/<your-partition>
+
+- Copy the boot files to the VFAT partition:
+    If you use the EFI stub method, the kernel acts also as an EFI executable.
+
+    You can just copy the bzImage to the EFI/boot/bootx64.efi path on the partition
+    so that it will automatically get booted, see the <Documentation/admin-guide/efi-stub.rst> page
+    for additional instructions regarding passage of kernel parameters and initramfs.
 
-	elilo bootloader with x86_64 support, elilo configuration file,
-	kernel image built in first step and corresponding
-	initrd. Instructions on building elilo and its dependencies
-	can be found in the elilo sourceforge project.
+    If you use a custom bootloader, refer to the relevant documentation for help on this part.
 
-- Boot to EFI shell and invoke elilo choosing the kernel image built
-  in first step.
 - If some or all EFI runtime services don't work, you can try following
   kernel command line parameters to turn off some or all EFI runtime
   services.
Signature · 1 line
2.39.5
Reviewed-by on v2 1/1
#1 lore raw
Quoted 52 lines · Nir Lichtman
Documentation/arch/x86/x86_64/uefi.rst +25 -5
index fbc30c9a071d..3949d83a9915 100644
@@ -12,14 +12,19 @@ with EFI firmware and specifications are listed below.
 
 1. UEFI specification:  http://www.uefi.org
 
-2. Booting Linux kernel on UEFI x86_64 platform requires bootloader
-   support. Elilo with x86_64 support can be used.
+2. Booting Linux kernel on UEFI x86_64 platform can either be
+   done using the <Documentation/admin-guide/efi-stub.rst> or using a separate bootloader.
 
 3. x86_64 platform with EFI/UEFI firmware.
 
 Mechanics
 ---------
 
+Refer to <Documentation/admin-guide/efi-stub.rst> to learn how to use the EFI stub.
+
+Below are general EFI setup guidelines on the x86_64 platform,
+regardless of whether you use the EFI stub or a separate bootloader.
+
 - Build the kernel with the following configuration::
 
 	CONFIG_FB_EFI=y
@@ -31,16 +36,27 @@ Mechanics
 	CONFIG_EFI=y
 	CONFIG_EFIVAR_FS=y or m		# optional
 
-- Create a VFAT partition on the disk
-- Copy the following to the VFAT partition:
+- Create a VFAT partition on the disk with the EFI System flag
+    You can do this with fdisk with the following commands:
+
+        1. g - initialize a GPT partition table
+        2. n - create a new partition
+        3. t - change the partition type to "EFI System" (number 1)
+        4. w - write and save the changes
+
+    Afterwards, initialize the VFAT filesystem by running mkfs::
+
+        mkfs.fat /dev/<your-partition>
+
+- Copy the boot files to the VFAT partition:
+    If you use the EFI stub method, the kernel acts also as an EFI executable.
+
+    You can just copy the bzImage to the EFI/boot/bootx64.efi path on the partition
+    so that it will automatically get booted, see the <Documentation/admin-guide/efi-stub.rst> page
+    for additional instructions regarding passage of kernel parameters and initramfs.
 
-	elilo bootloader with x86_64 support, elilo configuration file,

Documentation/arch/x86/x86_64/uefi.rst Mechanics · line 62

Quoted 10 lines
Documentation/arch/x86/x86_64/uefi.rst +1 -5
-	kernel image built in first step and corresponding
-	initrd. Instructions on building elilo and its dependencies
-	can be found in the elilo sourceforge project.
+    If you use a custom bootloader, refer to the relevant documentation for help on this part.
 
-- Boot to EFI shell and invoke elilo choosing the kernel image built
-  in first step.
 - If some or all EFI runtime services don't work, you can try following
   kernel command line parameters to turn off some or all EFI runtime
   services.

Looks good, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw
Quoted 16 lines · Bagas Sanjaya
Quoted 15 lines · Nir Lichtman
Documentation/arch/x86/x86_64/uefi.rst +2 -2
index fbc30c9a071d..3949d83a9915 100644
@@ -12,14 +12,19 @@ with EFI firmware and specifications are listed below.
 
 1. UEFI specification:  http://www.uefi.org
 
-2. Booting Linux kernel on UEFI x86_64 platform requires bootloader
-   support. Elilo with x86_64 support can be used.
+2. Booting Linux kernel on UEFI x86_64 platform can either be
+   done using the <Documentation/admin-guide/efi-stub.rst> or using a separate bootloader.
 
 3. x86_64 platform with EFI/UEFI firmware.
 

[..]

Quoted 7 lines
Quoted 3 lines

- If some or all EFI runtime services don't work, you can try following kernel command line parameters to turn off some or all EFI runtime services.

Looks good, thanks!

Thanks for the review! Small question:
I noticed that there is also a script in the kernel (genimage) which enables automation of building the image, including an image utilizing the EFI stub. The EFI stub image can be built by enabling the relavent EFI stub config options and then running "make hdimage", thing is that I couldn't get the script the to work yet (stuck on an error about missing EDK2/OMVF), but I could look deeper into this method as well and add it also to this doc, do you think it is also relavent?

Thanks,
Nir

maintainer
#3 lore raw
In reply to Nir Lichtman
Quoted 11 lines · Nir Lichtman

Problem: The x86_64 UEFI doc references Elilo which is an unmaintained/orphaned bootloader project. Also, on x86_64 a bootloader is technically not actually required since there is support for the Linux EFI stub.

Solution: Remove the references to Elilo from the doc and refer to the EFI stub doc page, update steps accordingly, and add more details about creation of the EFI partition to improve clarity.

---

I've applied this, but ...

Quoted 11 lines

v2: Fix list not rendered properly and minor wording fixes (thanks for the CR Bagas) Also fix to use shorter lines

 Documentation/arch/x86/x86_64/uefi.rst | 36 +++++++++++++++++++-------
 1 file changed, 26 insertions(+), 10 deletions(-)
Documentation/arch/x86/x86_64/uefi.rst +0 -0
index fbc30c9a071d..3949d83a9915 100644

Documentation/arch/x86/x86_64/uefi.rst with EFI firmware and specifications are listed below. · line 17

Quoted 8 lines
Documentation/arch/x86/x86_64/uefi.rst +2 -2
@@ -12,14 +12,19 @@ with EFI firmware and specifications are listed below.
 
 1. UEFI specification:  http://www.uefi.org
 
-2. Booting Linux kernel on UEFI x86_64 platform requires bootloader
-   support. Elilo with x86_64 support can be used.
+2. Booting Linux kernel on UEFI x86_64 platform can either be
+   done using the <Documentation/admin-guide/efi-stub.rst> or using a separate bootloader.
 

...I did take the liberty of wrapping the above line to fit within 80 columns.

Thanks,

jon