docs: qemu/virt platform documentation fixes and updates

- Correct the payload address in the RV64 examples that use
  fw_jump.elf.

- Change the qemu console configuration in the examples from
  "-display none -serial stdio" to "-nographic". This results in
  qemu handing down a CTRL-C on the emulated console to the VM
  instead of terminating the qemu process.

- Provide examples for RV32.

- Various text corrections.

Signed-off-by: Karsten Merker <merker@debian.org>
Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

1 files changed, 80 insertions, 11 deletions

diff --git a/docs/platform/qemu_virt.md b/docs/platform/qemu_virt.md
index 32575f9..27efeab 100644
--- a/docs/platform/qemu_virt.md
+++ b/docs/platform/qemu_virt.md
@@ -1,18 +1,18 @@
 QEMU RISC-V Virt Machine Platform
 =================================
 
-The **QEMU RISC-V Virt Machine** is virtual platform created for RISC-V
-software development and testing. It is also referred as
+The **QEMU RISC-V Virt Machine** is a virtual platform created for RISC-V
+software development and testing. It is also referred to as
 *QEMU RISC-V VirtIO machine* because it uses VirtIO devices for network,
 storage, and other types of IO.
 
-To build platform specific library and firmwares, provide the
+To build the platform-specific library and firmware images, provide the
 *PLATFORM=qemu/virt* parameter to the top level `make` command.
 
 Platform Options
 ----------------
 
-The *QEMU RISC-V Virt Machine* platform does not have any platform specific
+The *QEMU RISC-V Virt Machine* platform does not have any platform-specific
 options.
 
 Execution on QEMU RISC-V 64bit
@@ -27,7 +27,7 @@ make PLATFORM=qemu/virt
 
 Run:
 ```
-qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
+qemu-system-riscv64 -M virt -m 256M -nographic \
 	-kernel build/platform/qemu/virt/firmware/fw_payload.elf
 ```
 
@@ -43,19 +43,19 @@ make PLATFORM=qemu/virt FW_PAYLOAD_PATH=<uboot_build_directory>/u-boot.bin
 
 Run:
 ```
-qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
+qemu-system-riscv64 -M virt -m 256M -nographic \
 	-kernel build/platform/qemu/virt/firmware/fw_payload.elf
 ```
 or
 ```
-qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
+qemu-system-riscv64 -M virt -m 256M -nographic \
 	-kernel build/platform/qemu/virt/firmware/fw_jump.elf \
-	-device loader,file=<uboot_build_directory>/u-boot.bin,addr=0x80400000
+	-device loader,file=<uboot_build_directory>/u-boot.bin,addr=0x80200000
 ```
 
 **Linux Kernel Payload**
 
-Note: We assume that Linux kernel is compiled using
+Note: We assume that the Linux kernel is compiled using
 *arch/riscv/configs/defconfig*.
 
 Build:
@@ -65,7 +65,76 @@ make PLATFORM=qemu/virt FW_PAYLOAD_PATH=<linux_build_directory>/arch/riscv/boot/
 
 Run:
 ```
-qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
+qemu-system-riscv64 -M virt -m 256M -nographic \
+	-kernel build/platform/qemu/virt/firmware/fw_payload.elf \
+	-drive file=<path_to_linux_rootfs>,format=raw,id=hd0 \
+	-device virtio-blk-device,drive=hd0 \
+	-append "root=/dev/vda rw console=ttyS0"
+```
+or
+```
+qemu-system-riscv64 -M virt -m 256M -nographic \
+	-kernel build/platform/qemu/virt/firmware/fw_jump.elf \
+	-device loader,file=<linux_build_directory>/arch/riscv/boot/Image,addr=0x80200000 \
+	-drive file=<path_to_linux_rootfs>,format=raw,id=hd0 \
+	-device virtio-blk-device,drive=hd0 \
+	-append "root=/dev/vda rw console=ttyS0"
+```
+
+
+Execution on QEMU RISC-V 32bit
+------------------------------
+
+**No Payload Case**
+
+Build:
+```
+make PLATFORM=qemu/virt
+```
+
+Run:
+```
+qemu-system-riscv32 -M virt -m 256M -nographic \
+	-kernel build/platform/qemu/virt/firmware/fw_payload.elf
+```
+
+**U-Boot Payload**
+
+Note: the command line examples here assume that U-Boot was compiled using
+the `qemu-riscv32_smode_defconfig` configuration.
+
+Build:
+```
+make PLATFORM=qemu/virt FW_PAYLOAD_PATH=<uboot_build_directory>/u-boot.bin
+```
+
+Run:
+```
+qemu-system-riscv32 -M virt -m 256M -nographic \
+	-kernel build/platform/qemu/virt/firmware/fw_payload.elf
+```
+or
+```
+qemu-system-riscv32 -M virt -m 256M -nographic \
+	-kernel build/platform/qemu/virt/firmware/fw_jump.elf \
+	-device loader,file=<uboot_build_directory>/u-boot.bin,addr=0x80400000
+```
+
+**Linux Kernel Payload**
+
+Note: We assume that the Linux kernel is compiled using
+*arch/riscv/configs/rv32_defconfig* (kernel 5.1 and newer)
+respectively using *arch/riscv/configs/defconfig* plus setting
+CONFIG_ARCH_RV32I=y (kernel 5.0 and older).
+
+Build:
+```
+make PLATFORM=qemu/virt FW_PAYLOAD_PATH=<linux_build_directory>/arch/riscv/boot/Image
+```
+
+Run:
+```
+qemu-system-riscv32 -M virt -m 256M -nographic \
 	-kernel build/platform/qemu/virt/firmware/fw_payload.elf \
 	-drive file=<path_to_linux_rootfs>,format=raw,id=hd0 \
 	-device virtio-blk-device,drive=hd0 \
@@ -73,7 +142,7 @@ qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
 ```
 or
 ```
-qemu-system-riscv64 -M virt -m 256M -display none -serial stdio \
+qemu-system-riscv32 -M virt -m 256M -nographic \
 	-kernel build/platform/qemu/virt/firmware/fw_jump.elf \
 	-device loader,file=<linux_build_directory>/arch/riscv/boot/Image,addr=0x80400000 \
 	-drive file=<path_to_linux_rootfs>,format=raw,id=hd0 \