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.
Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
Cc: Cédric Le Goater <c...@kaod.org>
---
qemu-options.hx | 80 ++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 62 insertions(+), 18 deletions(-)
diff --git a/qemu-options.hx b/qemu-options.hx
index 377d22fbd8..9b0242f0ef 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,51 @@ 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 guests address space
+
+The last method is useful for quickly testing kernels but as there is
+no firmware to pass configuration information to the kernel it must
+either be built for the exact configuration or be handed a DTB blob
+which tells the kernel what drivers it needs.
+
+ERST
+
+SRST
+
+For x86 machines ``-bios`` will generally do the right thing with
+whatever it is given. For non-x86 machines the more strict ``-pflash``
+option needs an image that is sized for the flash device for the given
+machine type.
+
+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
+``-pflash file``
+ Use file as a parallel flash image.
+ERST
+
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.
+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 +3757,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 +4226,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 |
--
2.30.2
