1. Patchew
  2. QEMU
  3. View series

[PATCH v2] add a note on -shim to direct kernel boot docs

Gerd Hoffmann posted 1 patch 1 month, 1 week ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20260612161707.158029-1-kraxel@redhat.com
Maintainers: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
docs/system/linuxboot.rst | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
[PATCH v2] add a note on -shim to direct kernel boot docs
Posted by Gerd Hoffmann 1 month, 1 week ago 
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 docs/system/linuxboot.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
index f7573ab80a..c787481ccc 100644
--- a/docs/system/linuxboot.rst
+++ b/docs/system/linuxboot.rst
@@ -17,6 +17,23 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
 give the kernel command line arguments. The ``-initrd`` option can be
 used to provide an INITRD image.
 
+The ``-shim`` option specifies the ``shim.efi`` binary.  This is needed
+when you are booting UEFI firmware and using the ``-kernel`` option to
+tell UEFI to boot a specific kernel image, and the UEFI firmware you
+are booting has UEFI secure boot enabled.
+
+When this option is specified, the guest UEFI firmware will first
+load, verify and run the shim binary, which is typically signed by
+Microsoft so the firmware accepts it.  The shim binary in turn will
+load and verify the Linux kernel.  The kernel is typically signed by
+the distro and the certificates needed to verify them are compiled
+into the shim binary, so shim + kernel must come from the same Linux
+distribution.
+
+Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
+distro install media.  You might find a second shim copy in the
+``EFI/$distro/`` directory.
+
 If you do not need graphical output, you can disable it and redirect the
 virtual serial port and the QEMU monitor to the console with the
 ``-nographic`` option. The typical command line is:
-- 
2.54.0
Re: [PATCH v2] add a note on -shim to direct kernel boot docs
Posted by Pierrick Bouvier 1 month, 1 week ago 
On 6/12/2026 9:17 AM, Gerd Hoffmann wrote:
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/system/linuxboot.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 

This was merged into master (1d948f44240d51929f9051d997ea83e3213bdd18).
Thank you for your contribution!

Regards,
Pierrick
Re: [PATCH v2] add a note on -shim to direct kernel boot docs
Posted by Peter Maydell 1 month, 1 week ago 
On Fri, 12 Jun 2026 at 17:17, Gerd Hoffmann <kraxel@redhat.com> wrote:
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/system/linuxboot.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
>
> diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
> index f7573ab80a..c787481ccc 100644
> --- a/docs/system/linuxboot.rst
> +++ b/docs/system/linuxboot.rst
> @@ -17,6 +17,23 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
>  give the kernel command line arguments. The ``-initrd`` option can be
>  used to provide an INITRD image.
>
> +The ``-shim`` option specifies the ``shim.efi`` binary.  This is needed
> +when you are booting UEFI firmware and using the ``-kernel`` option to
> +tell UEFI to boot a specific kernel image, and the UEFI firmware you
> +are booting has UEFI secure boot enabled.
> +
> +When this option is specified, the guest UEFI firmware will first
> +load, verify and run the shim binary, which is typically signed by
> +Microsoft so the firmware accepts it.  The shim binary in turn will
> +load and verify the Linux kernel.  The kernel is typically signed by
> +the distro and the certificates needed to verify them are compiled
> +into the shim binary, so shim + kernel must come from the same Linux

extremely minor nit, I think I would say "and" rather than "+" here.

Anyway

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM
Re: [PATCH v2] add a note on -shim to direct kernel boot docs
Posted by Pierrick Bouvier 1 month, 1 week ago 
On 6/16/2026 1:21 AM, Peter Maydell wrote:
> On Fri, 12 Jun 2026 at 17:17, Gerd Hoffmann <kraxel@redhat.com> wrote:
>>
>> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
>> ---
>>  docs/system/linuxboot.rst | 17 +++++++++++++++++
>>  1 file changed, 17 insertions(+)
>>
>> diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
>> index f7573ab80a..c787481ccc 100644
>> --- a/docs/system/linuxboot.rst
>> +++ b/docs/system/linuxboot.rst
>> @@ -17,6 +17,23 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
>>  give the kernel command line arguments. The ``-initrd`` option can be
>>  used to provide an INITRD image.
>>
>> +The ``-shim`` option specifies the ``shim.efi`` binary.  This is needed
>> +when you are booting UEFI firmware and using the ``-kernel`` option to
>> +tell UEFI to boot a specific kernel image, and the UEFI firmware you
>> +are booting has UEFI secure boot enabled.
>> +
>> +When this option is specified, the guest UEFI firmware will first
>> +load, verify and run the shim binary, which is typically signed by
>> +Microsoft so the firmware accepts it.  The shim binary in turn will
>> +load and verify the Linux kernel.  The kernel is typically signed by
>> +the distro and the certificates needed to verify them are compiled
>> +into the shim binary, so shim + kernel must come from the same Linux
> 
> extremely minor nit, I think I would say "and" rather than "+" here.
> 
> Anyway
> 
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> 
> thanks
> -- PMM

Thanks Peter, I'll pull this and add the change you suggested.

Regards,
Pierrick
Re: [PATCH v2] add a note on -shim to direct kernel boot docs
Posted by Pierrick Bouvier 1 month, 1 week ago 
On 6/12/2026 9:17 AM, Gerd Hoffmann wrote:
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/system/linuxboot.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
> index f7573ab80a..c787481ccc 100644
> --- a/docs/system/linuxboot.rst
> +++ b/docs/system/linuxboot.rst
> @@ -17,6 +17,23 @@ Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
>  give the kernel command line arguments. The ``-initrd`` option can be
>  used to provide an INITRD image.
>  
> +The ``-shim`` option specifies the ``shim.efi`` binary.  This is needed
> +when you are booting UEFI firmware and using the ``-kernel`` option to
> +tell UEFI to boot a specific kernel image, and the UEFI firmware you
> +are booting has UEFI secure boot enabled.
> +
> +When this option is specified, the guest UEFI firmware will first
> +load, verify and run the shim binary, which is typically signed by
> +Microsoft so the firmware accepts it.  The shim binary in turn will
> +load and verify the Linux kernel.  The kernel is typically signed by
> +the distro and the certificates needed to verify them are compiled
> +into the shim binary, so shim + kernel must come from the same Linux
> +distribution.
> +
> +Usually you can find shim.efi as ``EFI/BOOT/BOOT{X64,AA64}.EFI`` on
> +distro install media.  You might find a second shim copy in the
> +``EFI/$distro/`` directory.
> +
>  If you do not need graphical output, you can disable it and redirect the
>  virtual serial port and the QEMU monitor to the console with the
>  ``-nographic`` option. The typical command line is:

Good for me, I'll wait for additional reviews to pull it directly.
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>

Regards,
Pierrick

Patchew 2.1-devel-ea86937

© 2016 - 2026 Red Hat, Inc.