1 files changed, 75 insertions, 0 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 4cf72612bf..2330d5e895 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -3491,6 +3491,81 @@
             <filename>runqemu</filename> has been ported to Python and has
             changed behavior in some cases.
         </para>
+
+        <para>
+            The new <filename>runqemu</filename> is a Python script.
+            The script requires a configuration file in the following
+            form in order to boot the BSP:
+            <literallayout class='monospaced'>
+     <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf
+            </literallayout>
+            Machine knowledge is no longer hardcoded into
+            <filename>runqemu</filename>.
+            You can use the <filename>qemuboot</filename> configuration file
+            to define the BSP's own arguments and to make it bootable
+            with <filename>runqemu</filename>.
+            <note>
+                Previous usage patterns are continued to be supported.
+            </note>
+            The <filename>qemuboot.conf</filename> file is generated by the
+            <filename>qemuboot</filename>
+            class when the root filesystem is being build (i.e.
+            build rootfs).
+            QEMU boot arguments can be set in BSP's configuration file and
+            the <filename>qemuboot</filename> class will save them to
+            <filename>qemuboot.conf</filename>.
+        </para>
+
+        <para>
+            Following is a list of variables that can be set in configuration
+            files such as <filename>bsp.conf</filename> to enable the BSP
+            to be booted by <filename>runqemu</filename>:
+            <note>
+                "QB" means "QEMU Boot".
+            </note>
+            <literallayout class='monospaced'>
+     QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
+     QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
+     QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
+     QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
+     QB_MEM: Memory (e.g. "-m 512")
+     QB_MACHINE: QEMU machine (e.g. "-machine virt")
+     QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
+     QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
+     QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
+                               option (e.g. "console=ttyS0 console=tty")
+     QB_DTB: QEMU dtb name
+     QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
+     QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
+                   when QB_AUDIO_DRV is set.
+     QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
+     QB_TAP_OPT: Network option for 'tap' mode (e.g.
+                 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
+                  runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
+     QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
+     QB_ROOTFS_OPT: Used as rootfs (e.g.
+                    "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
+                    runqemu will replace "@ROOTFS@" with the one which is used, such as
+                    core-image-minimal-qemuarm64.ext4.
+     QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
+     QB_TCPSERIAL_OPT: tcp serial port option (e.g.
+                       " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device      virtconsole,chardev=virtcon"
+                       runqemu will replace "@PORT@" with the port number which is used.
+            </literallayout>
+        </para>
+
+        <para>
+            To use <filename>runqemu</filename>, set
+            <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
+            as follows and run <filename>runqemu</filename>:
+            <note>
+                For command-line syntax, use
+                <filename>runqemu help</filename>.
+            </note>
+            <literallayout class='monospaced'>
+     IMAGE_CLASSES += "qemuboot"
+            </literallayout>
+        </para>
     </section>
 
     <section id='migration-2.2-default-linker-hash-style-changed'>