[PATCH] Documentation: Fix x86_64 UEFI outdated references to elilo

[PATCH] Documentation: Fix x86_64 UEFI outdated references to elilo

[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.

Signed-off-by: Nir Lichtman <nir@lichtman.org>
---
 Documentation/arch/x86/x86_64/uefi.rst | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/Documentation/arch/x86/x86_64/uefi.rst b/Documentation/arch/x86/x86_64/uefi.rst
index fbc30c9a071d..c056063f49d5 100644
--- a/Documentation/arch/x86/x86_64/uefi.rst
+++ b/Documentation/arch/x86/x86_64/uefi.rst
@@ -12,14 +12,16 @@ 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> for general setup guidelines on usage of the EFI stub, the following are setup specifics for EFI in general on the x86_64 platform.
+
 - Build the kernel with the following configuration::
 
 	CONFIG_FB_EFI=y
@@ -31,16 +33,20 @@ 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>
 
-	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.
+- Copy the boot files to the VFAT partition:
+    If you use the EFI stub method, the kernel acts also as an EFI executable, and 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.
+    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.
-- 
2.39.5

Re: [PATCH] Documentation: Fix x86_64 UEFI outdated references to elilo

[Nir Lichtman]

On Mon, Jan 06, 2025 at 10:35:27PM +0000, Nir Lichtman wrote:
> 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.
> 
> Signed-off-by: Nir Lichtman <nir@lichtman.org>
> ---

Adding also the x86 arch maintainers to the thread (forgot).

>  Documentation/arch/x86/x86_64/uefi.rst | 26 ++++++++++++++++----------
>  1 file changed, 16 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/arch/x86/x86_64/uefi.rst b/Documentation/arch/x86/x86_64/uefi.rst
> index fbc30c9a071d..c056063f49d5 100644
> --- a/Documentation/arch/x86/x86_64/uefi.rst
> +++ b/Documentation/arch/x86/x86_64/uefi.rst
> @@ -12,14 +12,16 @@ 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> for general setup guidelines on usage of the EFI stub, the following are setup specifics for EFI in general on the x86_64 platform.
> +
>  - Build the kernel with the following configuration::
>  
>  	CONFIG_FB_EFI=y
> @@ -31,16 +33,20 @@ 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>
>  
> -	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.
> +- Copy the boot files to the VFAT partition:
> +    If you use the EFI stub method, the kernel acts also as an EFI executable, and 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.
> +    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.
> -- 
> 2.39.5
> 

Re: [PATCH] Documentation: Fix x86_64 UEFI outdated references to elilo

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 956 bytes --]

On Mon, Jan 06, 2025 at 10:35:26PM +0000, Nir Lichtman wrote:
> +Refer to <Documentation/admin-guide/efi-stub.rst> for general setup guidelines on usage of the EFI stub, the following are setup specifics for EFI in general on the x86_64 platform.

"... for how to use EFI stub. Below is general EFI setup on x86_64 platform,
regardless of whether using EFI stub or separate bootloader."

> -- 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

I see running paragraph instead of numbered list in htmldocs output.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] Documentation: Fix x86_64 UEFI outdated references to elilo

[Nir Lichtman]

On Wed, Jan 08, 2025 at 08:46:24AM +0700, Bagas Sanjaya wrote:
> On Mon, Jan 06, 2025 at 10:35:26PM +0000, Nir Lichtman wrote:
> > +Refer to <Documentation/admin-guide/efi-stub.rst> for general setup guidelines on usage of the EFI stub, the following are setup specifics for EFI in general on the x86_64 platform.
> 
> "... for how to use EFI stub. Below is general EFI setup on x86_64 platform,
> regardless of whether using EFI stub or separate bootloader."
> 

Thanks will fix

> > -- 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
> 
> I see running paragraph instead of numbered list in htmldocs output.

My bad thanks for checking, will shortly send a v2 with the fixes, thanks for the review!

Nir

> 
> Thanks.
> 
> -- 
> An old man doll... just what I always wanted! - Clara