[v2] qemu-options: bring the kernel and image options together

How to control the booting of QEMU is often a source of confusion for
users. Bring the options that control this together in the manual
pages and add some verbiage to describe when each option is
appropriate. This attempts to codify some of the knowledge expressed
in:

  https://stackoverflow.com/questions/58420670/qemu-bios-vs-kernel-vs-device-loader-file/58434837#58434837

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Cédric Le Goater <clg@kaod.org>
Message-Id: <20220622145052.4012981-1-alex.bennee@linaro.org>

---
v2
  - fix third and last reference for kernel and generic loader
  - more verbiage following feedback from Peter
  - mention Peter's write up in the commit message
---
 qemu-options.hx | 90 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 72 insertions(+), 18 deletions(-)

On Thu, 7 Jul 2022 at 16:11, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> How to control the booting of QEMU is often a source of confusion for
> users. Bring the options that control this together in the manual
> pages and add some verbiage to describe when each option is
> appropriate. This attempts to codify some of the knowledge expressed
> in:
>
>   https://stackoverflow.com/questions/58420670/qemu-bios-vs-kernel-vs-device-loader-file/58434837#58434837
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Cédric Le Goater <clg@kaod.org>
> Message-Id: <20220622145052.4012981-1-alex.bennee@linaro.org>
>
> ---
> v2
>   - fix third and last reference for kernel and generic loader
>   - more verbiage following feedback from Peter
>   - mention Peter's write up in the commit message
> ---
>  qemu-options.hx | 90 +++++++++++++++++++++++++++++++++++++++----------
>  1 file changed, 72 insertions(+), 18 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 377d22fbd8..70e7f98882 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1585,13 +1585,6 @@ SRST
>      Use file as SecureDigital card image.
>  ERST
>
> -DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
> -    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
> -SRST
> -``-pflash file``
> -    Use file as a parallel flash image.
> -ERST
> -
>  DEF("snapshot", 0, QEMU_OPTION_snapshot,
>      "-snapshot       write to temporary files instead of disk image files\n",
>      QEMU_ARCH_ALL)
> @@ -3680,12 +3673,61 @@ DEFHEADING()
>
>  #endif
>
> -DEFHEADING(Linux/Multiboot boot specific:)
> +DEFHEADING(Boot Image or Kernel specific:)
> +SRST
> +There are broadly 4 ways you can boot a system with QEMU.
> +
> + - specify a firmware and let it control finding a kernel
> + - specify a firmware and pass a hint to the kernel to boot
> + - direct kernel image boot
> + - manually load files into the guest's address space
> +
> +The third method is useful for quickly testing kernels but as there is
> +no firmware to pass configuration information to the kernel the
> +hardware must either be probable, the kernel built for the exact

"probeable"

> +configuration or passed some configuration data (e.g. a DTB blob)
> +which tells the kernel what drivers it needs. This exact details are
> +often hardware specific.
> +
> +The final method is the most generic way of loading images into the
> +guest address space and used mostly for ``bare metal`` type
> +development where the reset vectors of the processor are taken into
> +account.
> +
> +ERST
> +
> +SRST
> +
> +For x86 machines and some other architectures ``-bios`` will generally
> +do the right thing with whatever it is given. For other machines the
> +more strict ``-pflash`` option needs an image that is sized for the
> +flash device for the given machine type.
> +
> +Please see the :ref:`system-targets-ref` section of the manual for
> +more detailed documentation.
> +
> +ERST
> +
> +DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
> +    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
> +SRST
> +``-bios file``
> +    Set the filename for the BIOS.
> +ERST
> +
> +DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
> +    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
>  SRST
> -When using these options, you can use a given Linux or Multiboot kernel
> -without installing it in the disk image. It can be useful for easier
> -testing of various kernels.
> +``-pflash file``
> +    Use file as a parallel flash image.
> +ERST
>
> +SRST
> +
> +The kernel options were designed to work with Linux kernels although
> +other things (like hypervisors) can be packaged up as a kernel
> +executable image. The exact format of a executable image is usually
> +architecture specific.

"The way in which the kernel is started (what address it is loaded at,
what if any information is passed to it via CPU registers, the state
of the hardware when it is started, and so on) is also architecture
specific. Typically it follows the specification laid down by the
Linux kernel for how kernels for that architecture must be started."


>  ERST
>
> @@ -3725,6 +3767,25 @@ SRST
>      kernel on boot.
>  ERST
>
> +SRST
> +
> +Finally you can also manually load images directly into the address
> +space of the guest. This is most useful for developers who already
> +know the layout of their guest and take care to ensure something sane
> +will happen when the reset vector executes.
> +
> +The generic loader can be invoked by using the loader device:
> +
> +``-device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]``
> +
> +there is also the guest loader which operates in a similar way but
> +tweaks the DTB so a hypervisor loaded via ``-kernel`` can find where
> +the guest image is:
> +
> +``-device guest-loader,addr=<addr>[,kernel=<path>,[bootargs=<arguments>]][,initrd=<path>]``
> +
> +ERST
> +
>  DEFHEADING()

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

thanks
-- PMM

On 7/7/22 17:10, Alex Bennée wrote:
> How to control the booting of QEMU is often a source of confusion for
> users. Bring the options that control this together in the manual
> pages and add some verbiage to describe when each option is
> appropriate. This attempts to codify some of the knowledge expressed
> in:
> 
>    https://stackoverflow.com/questions/58420670/qemu-bios-vs-kernel-vs-device-loader-file/58434837#58434837
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Cédric Le Goater <clg@kaod.org>
> Message-Id: <20220622145052.4012981-1-alex.bennee@linaro.org>

LGTM,

Reviewed-by: Cédric Le Goater <clg@kaod.org>

Thanks,

C.


> 
> ---
> v2
>    - fix third and last reference for kernel and generic loader
>    - more verbiage following feedback from Peter
>    - mention Peter's write up in the commit message
> ---
>   qemu-options.hx | 90 +++++++++++++++++++++++++++++++++++++++----------
>   1 file changed, 72 insertions(+), 18 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 377d22fbd8..70e7f98882 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1585,13 +1585,6 @@ SRST
>       Use file as SecureDigital card image.
>   ERST
>   
> -DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
> -    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
> -SRST
> -``-pflash file``
> -    Use file as a parallel flash image.
> -ERST
> -
>   DEF("snapshot", 0, QEMU_OPTION_snapshot,
>       "-snapshot       write to temporary files instead of disk image files\n",
>       QEMU_ARCH_ALL)
> @@ -3680,12 +3673,61 @@ DEFHEADING()
>   
>   #endif
>   
> -DEFHEADING(Linux/Multiboot boot specific:)
> +DEFHEADING(Boot Image or Kernel specific:)
> +SRST
> +There are broadly 4 ways you can boot a system with QEMU.
> +
> + - specify a firmware and let it control finding a kernel
> + - specify a firmware and pass a hint to the kernel to boot
> + - direct kernel image boot
> + - manually load files into the guest's address space
> +
> +The third method is useful for quickly testing kernels but as there is
> +no firmware to pass configuration information to the kernel the
> +hardware must either be probable, the kernel built for the exact
> +configuration or passed some configuration data (e.g. a DTB blob)
> +which tells the kernel what drivers it needs. This exact details are
> +often hardware specific.
> +
> +The final method is the most generic way of loading images into the
> +guest address space and used mostly for ``bare metal`` type
> +development where the reset vectors of the processor are taken into
> +account.
> +
> +ERST
> +
> +SRST
> +
> +For x86 machines and some other architectures ``-bios`` will generally
> +do the right thing with whatever it is given. For other machines the
> +more strict ``-pflash`` option needs an image that is sized for the
> +flash device for the given machine type.
> +
> +Please see the :ref:`system-targets-ref` section of the manual for
> +more detailed documentation.
> +
> +ERST
> +
> +DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
> +    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
> +SRST
> +``-bios file``
> +    Set the filename for the BIOS.
> +ERST
> +
> +DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
> +    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
>   SRST
> -When using these options, you can use a given Linux or Multiboot kernel
> -without installing it in the disk image. It can be useful for easier
> -testing of various kernels.
> +``-pflash file``
> +    Use file as a parallel flash image.
> +ERST
>   
> +SRST
> +
> +The kernel options were designed to work with Linux kernels although
> +other things (like hypervisors) can be packaged up as a kernel
> +executable image. The exact format of a executable image is usually
> +architecture specific.
>   
>   ERST
>   
> @@ -3725,6 +3767,25 @@ SRST
>       kernel on boot.
>   ERST
>   
> +SRST
> +
> +Finally you can also manually load images directly into the address
> +space of the guest. This is most useful for developers who already
> +know the layout of their guest and take care to ensure something sane
> +will happen when the reset vector executes.
> +
> +The generic loader can be invoked by using the loader device:
> +
> +``-device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]``
> +
> +there is also the guest loader which operates in a similar way but
> +tweaks the DTB so a hypervisor loaded via ``-kernel`` can find where
> +the guest image is:
> +
> +``-device guest-loader,addr=<addr>[,kernel=<path>,[bootargs=<arguments>]][,initrd=<path>]``
> +
> +ERST
> +
>   DEFHEADING()
>   
>   DEFHEADING(Debug/Expert options:)
> @@ -4175,13 +4236,6 @@ SRST
>       To list all the data directories, use ``-L help``.
>   ERST
>   
> -DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
> -    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
> -SRST
> -``-bios file``
> -    Set the filename for the BIOS.
> -ERST
> -
>   DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
>       "-enable-kvm     enable KVM full virtualization support\n",
>       QEMU_ARCH_ARM | QEMU_ARCH_I386 | QEMU_ARCH_MIPS | QEMU_ARCH_PPC |

Alex Bennée <alex.bennee@linaro.org> writes:

> How to control the booting of QEMU is often a source of confusion for
> users. Bring the options that control this together in the manual
> pages and add some verbiage to describe when each option is
> appropriate. This attempts to codify some of the knowledge expressed
> in:
>
>   https://stackoverflow.com/questions/58420670/qemu-bios-vs-kernel-vs-device-loader-file/58434837#58434837
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Cédric Le Goater <clg@kaod.org>
> Message-Id: <20220622145052.4012981-1-alex.bennee@linaro.org>

Queued to testing/next, thanks.