[PATCH v2 38/38] doc: Add a reST document for qemu-ppce500

[Bin Meng]

Add a reST document to describe how to build and run U-Boot for
the QEMU ppce500 machine.

Signed-off-by: Bin Meng <bmeng.cn at gmail.com>
Reviewed-by: Simon Glass <sjg at chromium.org>

---

Changes in v2:
- add descriptions for VirtIO BLK, RTC and power off

 doc/board/emulation/index.rst        |  1 +
 doc/board/emulation/qemu-ppce500.rst | 88 ++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 doc/board/emulation/qemu-ppce500.rst

diff --git a/doc/board/emulation/index.rst b/doc/board/emulation/index.rst
index a09ead1..be66b6b 100644
--- a/doc/board/emulation/index.rst
+++ b/doc/board/emulation/index.rst
@@ -8,6 +8,7 @@ Emulation
 
    qemu-arm
    qemu-mips
+   qemu-ppce500
    qemu-riscv
    qemu-x86
    qemu_capsule_update
diff --git a/doc/board/emulation/qemu-ppce500.rst b/doc/board/emulation/qemu-ppce500.rst
new file mode 100644
index 0000000..0a5c86c
--- /dev/null
+++ b/doc/board/emulation/qemu-ppce500.rst
@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2021, Bin Meng <bmeng.cn at gmail.com>
+
+QEMU PPC E500
+=============
+
+QEMU for PPC supports a special 'ppce500' machine designed for emulation and
+virtualization purposes. This document describes how to run U-Boot under it.
+
+The QEMU ppce500 machine models a generic PowerPC E500 virtual machine with
+support for the VirtIO standard networking device connected to the built-in
+PCI host controller. Some common devices in the CCSBAR space are modeled,
+including MPIC, 16550A UART devices, GPIO, I2C and PCI host controller with
+MSI delivery to MPIC. It uses device-tree to pass configuration information
+to guest software.
+
+Building U-Boot
+---------------
+Set the CROSS_COMPILE environment variable as usual, and run::
+
+    $ make qemu-ppce500_defconfig
+    $ make
+
+Running U-Boot
+--------------
+The minimal QEMU command line to get U-Boot up and running is::
+
+    $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot
+
+You can also run U-Boot using 'qemu-system-ppc64'::
+
+    $ qemu-system-ppc64 -nographic -machine ppce500 -bios u-boot
+
+The commands above create a target with 128 MiB memory by default. A freely
+configurable amount of RAM can be created via the '-m' parameter. For example,
+'-m 2G' creates 2 GiB memory for the target, and the memory node in the
+embedded DTB created by QEMU reflects the new setting.
+
+Both qemu-system-ppc and qemu-system-ppc64 provide emulation for the following
+32-bit PowerPC CPUs:
+
+* e500v2
+* e500mc
+
+Additionally qemu-system-ppc64 provides support for the following 64-bit CPUs:
+
+* e5500
+* e6500
+
+The CPU type can be specified via the '-cpu' command line. If not specified,
+it creates a machine with e500v2 core. The following example shows an e6500
+based machine creation::
+
+    $ qemu-system-ppc64 -nographic -machine ppce500 -cpu e6500 -bios u-boot
+
+When U-Boot boots, you will notice the following::
+
+    CPU:   Unknown, Version: 0.0, (0x00000000)
+    Core:  e6500, Version: 2.0, (0x80400020)
+
+This is because we only specified a core name to QEMU and it does not have a
+meaningful SVR value which represents an actual SoC that integrates such core.
+You can specify a real world SoC device that QEMU has built-in support but all
+these SoCs are e500v2 based MPC85xx series, hence you cannot test anything
+built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500).
+
+By default a VirtIO standard PCI networking device is connected as an ethernet
+interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by::
+
+    $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot \
+                      -nic tap,ifname=tap0,script=no,downscript=no,model=e1000
+
+VirtIO BLK driver is also enabled to support booting from a disk image where
+a kernel image is stored. Append the following to QEMU::
+
+    -drive file=disk.img,format=raw,id=disk0 -device virtio-blk-pci,drive=disk0
+
+Pericom pt7c4338 RTC is supported so we can use the 'date' command::
+
+    => date
+    Date: 2021-02-18 (Thursday)    Time: 15:33:20
+
+Additionally, 'poweroff' command is supported to shut down the QEMU session::
+
+    => poweroff
+    poweroff ...
+
+These have been tested in QEMU 5.2.0.
-- 
2.7.4