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 @@
runqemu has been ported to Python and has
changed behavior in some cases.
+
+
+ The new runqemu is a Python script.
+ The script requires a configuration file in the following
+ form in order to boot the BSP:
+
+ image-name-machine.qemuboot.conf
+
+ Machine knowledge is no longer hardcoded into
+ runqemu.
+ You can use the qemuboot configuration file
+ to define the BSP's own arguments and to make it bootable
+ with runqemu.
+
+ Previous usage patterns are continued to be supported.
+
+ The qemuboot.conf file is generated by the
+ qemuboot
+ 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 qemuboot class will save them to
+ qemuboot.conf.
+
+
+
+ Following is a list of variables that can be set in configuration
+ files such as bsp.conf to enable the BSP
+ to be booted by runqemu:
+
+ "QB" means "QEMU Boot".
+
+
+ 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.
+
+
+
+
+ To use runqemu, set
+ IMAGE_CLASSES
+ as follows and run runqemu:
+
+ For command-line syntax, use
+ runqemu help.
+
+
+ IMAGE_CLASSES += "qemuboot"
+
+